@databricks/appkit 0.8.0 → 0.9.0

package/dist/registry/types.js.map

@@ -1 +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"}
+{"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 and permissions are generated from plugin-manifest.schema.json\n * (see types.generated.ts). Hand-written interfaces below define the registry API.\n */\n\n// Re-export generated registry types (enum + const must be value exports for runtime)\nimport {\n  type AppPermission,\n  type DatabasePermission,\n  type ExperimentPermission,\n  type GenieSpacePermission,\n  type JobPermission,\n  PERMISSION_HIERARCHY_BY_TYPE,\n  PERMISSIONS_BY_TYPE,\n  type ResourcePermission,\n  ResourceType,\n  type SecretPermission,\n  type ServingEndpointPermission,\n  type SqlWarehousePermission,\n  type UcConnectionPermission,\n  type UcFunctionPermission,\n  type VectorSearchIndexPermission,\n  type VolumePermission,\n} from \"./types.generated\";\n\nexport {\n  PERMISSION_HIERARCHY_BY_TYPE,\n  PERMISSIONS_BY_TYPE,\n  ResourceType,\n  type AppPermission,\n  type DatabasePermission,\n  type ExperimentPermission,\n  type GenieSpacePermission,\n  type JobPermission,\n  type ResourcePermission,\n  type SecretPermission,\n  type ServingEndpointPermission,\n  type SqlWarehousePermission,\n  type UcConnectionPermission,\n  type UcFunctionPermission,\n  type VectorSearchIndexPermission,\n  type VolumePermission,\n};\n\n// ============================================================================\n// Hand-written interfaces (not in JSON schema)\n// ============================================================================\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":""}

package/dist/schemas/plugin-manifest.schema.json

@@ -0,0 +1,439 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+  "title": "AppKit Plugin Manifest",
+  "description": "Schema for Databricks AppKit plugin manifest files. Defines plugin metadata, resource requirements, and configuration options.",
+  "type": "object",
+  "required": ["name", "displayName", "description", "resources"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to the JSON Schema for validation"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Plugin identifier. Must be lowercase, start with a letter, and contain only letters, numbers, and hyphens.",
+      "examples": ["analytics", "server", "my-custom-plugin"]
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable display name for UI and CLI",
+      "examples": ["Analytics Plugin", "Server Plugin"]
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Brief description of what the plugin does",
+      "examples": ["SQL query execution against Databricks SQL Warehouses"]
+    },
+    "resources": {
+      "type": "object",
+      "required": ["required", "optional"],
+      "description": "Databricks resource requirements for this plugin",
+      "properties": {
+        "required": {
+          "type": "array",
+          "description": "Resources that must be available for the plugin to function",
+          "items": {
+            "$ref": "#/$defs/resourceRequirement"
+          }
+        },
+        "optional": {
+          "type": "array",
+          "description": "Resources that enhance functionality but are not mandatory",
+          "items": {
+            "$ref": "#/$defs/resourceRequirement"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "config": {
+      "type": "object",
+      "description": "Configuration schema for the plugin",
+      "properties": {
+        "schema": {
+          "$ref": "#/$defs/configSchema"
+        }
+      },
+      "additionalProperties": false
+    },
+    "author": {
+      "type": "string",
+      "description": "Author name or organization"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?$",
+      "description": "Plugin version (semver format)",
+      "examples": ["1.0.0", "2.1.0-beta.1"]
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to the plugin's source repository"
+    },
+    "keywords": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Keywords for plugin discovery"
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier",
+      "examples": ["Apache-2.0", "MIT"]
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "resourceType": {
+      "type": "string",
+      "enum": [
+        "secret",
+        "job",
+        "sql_warehouse",
+        "serving_endpoint",
+        "volume",
+        "vector_search_index",
+        "uc_function",
+        "uc_connection",
+        "database",
+        "genie_space",
+        "experiment",
+        "app"
+      ],
+      "description": "Type of Databricks resource"
+    },
+    "secretPermission": {
+      "type": "string",
+      "enum": ["READ", "WRITE", "MANAGE"],
+      "description": "Permission for secret resources (order: weakest to strongest)"
+    },
+    "jobPermission": {
+      "type": "string",
+      "enum": ["CAN_VIEW", "CAN_MANAGE_RUN", "CAN_MANAGE"],
+      "description": "Permission for job resources (order: weakest to strongest)"
+    },
+    "sqlWarehousePermission": {
+      "type": "string",
+      "enum": ["CAN_USE", "CAN_MANAGE"],
+      "description": "Permission for SQL warehouse resources (order: weakest to strongest)"
+    },
+    "servingEndpointPermission": {
+      "type": "string",
+      "enum": ["CAN_VIEW", "CAN_QUERY", "CAN_MANAGE"],
+      "description": "Permission for serving endpoint resources (order: weakest to strongest)"
+    },
+    "volumePermission": {
+      "type": "string",
+      "enum": ["READ_VOLUME", "WRITE_VOLUME"],
+      "description": "Permission for Unity Catalog volume resources"
+    },
+    "vectorSearchIndexPermission": {
+      "type": "string",
+      "enum": ["SELECT"],
+      "description": "Permission for vector search index resources"
+    },
+    "ucFunctionPermission": {
+      "type": "string",
+      "enum": ["EXECUTE"],
+      "description": "Permission for Unity Catalog function resources"
+    },
+    "ucConnectionPermission": {
+      "type": "string",
+      "enum": ["USE_CONNECTION"],
+      "description": "Permission for Unity Catalog connection resources"
+    },
+    "databasePermission": {
+      "type": "string",
+      "enum": ["CAN_CONNECT_AND_CREATE"],
+      "description": "Permission for database resources"
+    },
+    "genieSpacePermission": {
+      "type": "string",
+      "enum": ["CAN_VIEW", "CAN_RUN", "CAN_EDIT", "CAN_MANAGE"],
+      "description": "Permission for Genie Space resources (order: weakest to strongest)"
+    },
+    "experimentPermission": {
+      "type": "string",
+      "enum": ["CAN_READ", "CAN_EDIT", "CAN_MANAGE"],
+      "description": "Permission for MLflow experiment resources (order: weakest to strongest)"
+    },
+    "appPermission": {
+      "type": "string",
+      "enum": ["CAN_USE"],
+      "description": "Permission for Databricks App resources"
+    },
+    "resourceFieldEntry": {
+      "type": "object",
+      "required": ["env"],
+      "properties": {
+        "env": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*$",
+          "description": "Environment variable name for this field",
+          "examples": ["DATABRICKS_CACHE_INSTANCE", "SECRET_SCOPE"]
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description for this field"
+        }
+      },
+      "additionalProperties": false
+    },
+    "resourceRequirement": {
+      "type": "object",
+      "required": [
+        "type",
+        "alias",
+        "resourceKey",
+        "description",
+        "permission",
+        "fields"
+      ],
+      "properties": {
+        "type": {
+          "$ref": "#/$defs/resourceType"
+        },
+        "alias": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable label for UI/display only. Deduplication uses resourceKey, not alias.",
+          "examples": ["SQL Warehouse", "Secret", "Vector search index"]
+        },
+        "resourceKey": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Stable key for machine use: deduplication, env naming, composite keys, app.yaml. Required for registry lookup.",
+          "examples": ["sql-warehouse", "database", "secret"]
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable description of why this resource is needed"
+        },
+        "permission": {
+          "type": "string",
+          "description": "Required permission level. Validated per resource type by the allOf/if-then rules below."
+        },
+        "fields": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/resourceFieldEntry"
+          },
+          "minProperties": 1,
+          "description": "Map of field name to env and optional description. Single-value types use one key (e.g. id); multi-value (database, secret) use multiple (e.g. instance_name, database_name or scope, key)."
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "secret" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/secretPermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "job" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": { "permission": { "$ref": "#/$defs/jobPermission" } }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "sql_warehouse" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/sqlWarehousePermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "serving_endpoint" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/servingEndpointPermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "volume" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/volumePermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "vector_search_index" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/vectorSearchIndexPermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "uc_function" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/ucFunctionPermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "uc_connection" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/ucConnectionPermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "database" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/databasePermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "genie_space" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/genieSpacePermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "experiment" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/experimentPermission" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "app" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": { "permission": { "$ref": "#/$defs/appPermission" } }
+          }
+        }
+      ]
+    },
+    "configSchemaProperty": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["object", "array", "string", "number", "boolean", "integer"]
+        },
+        "description": {
+          "type": "string"
+        },
+        "default": {},
+        "enum": {
+          "type": "array"
+        },
+        "properties": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/configSchemaProperty"
+          }
+        },
+        "items": {
+          "$ref": "#/$defs/configSchemaProperty"
+        },
+        "minimum": {
+          "type": "number"
+        },
+        "maximum": {
+          "type": "number"
+        },
+        "minLength": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxLength": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "required": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "configSchema": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["object", "array", "string", "number", "boolean"]
+        },
+        "properties": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/configSchemaProperty"
+          }
+        },
+        "items": {
+          "$ref": "#/$defs/configSchema"
+        },
+        "required": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": {
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}

package/dist/schemas/template-plugins.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://databricks.github.io/appkit/schemas/template-plugins.schema.json",
+  "title": "AppKit Template Plugins Manifest",
+  "description": "Aggregated plugin manifest for AppKit templates. Read by Databricks CLI during init to discover available plugins and their resource requirements.",
+  "type": "object",
+  "required": ["version", "plugins"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to the JSON Schema for validation"
+    },
+    "version": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Schema version for the template plugins manifest"
+    },
+    "plugins": {
+      "type": "object",
+      "description": "Map of plugin name to plugin manifest with package source",
+      "additionalProperties": {
+        "$ref": "#/$defs/templatePlugin"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "templatePlugin": {
+      "type": "object",
+      "required": [
+        "name",
+        "displayName",
+        "description",
+        "package",
+        "resources"
+      ],
+      "description": "Plugin manifest with package source information",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Plugin identifier. Must be lowercase, start with a letter, and contain only letters, numbers, and hyphens.",
+          "examples": ["analytics", "server", "my-custom-plugin"]
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable display name for UI and CLI",
+          "examples": ["Analytics Plugin", "Server Plugin"]
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Brief description of what the plugin does",
+          "examples": ["SQL query execution against Databricks SQL Warehouses"]
+        },
+        "package": {
+          "type": "string",
+          "minLength": 1,
+          "description": "NPM package name that provides this plugin",
+          "examples": ["@databricks/appkit", "@my-org/custom-plugin"]
+        },
+        "requiredByTemplate": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, this plugin is required by the template and cannot be deselected during CLI init. The user will only be prompted to configure its resources. When absent or false, the plugin is optional and the user can choose whether to include it."
+        },
+        "resources": {
+          "type": "object",
+          "required": ["required", "optional"],
+          "description": "Databricks resource requirements for this plugin",
+          "properties": {
+            "required": {
+              "type": "array",
+              "description": "Resources that must be available for the plugin to function",
+              "items": {
+                "$ref": "#/$defs/resourceRequirement"
+              }
+            },
+            "optional": {
+              "type": "array",
+              "description": "Resources that enhance functionality but are not mandatory",
+              "items": {
+                "$ref": "#/$defs/resourceRequirement"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "resourceType": {
+      "$ref": "plugin-manifest.schema.json#/$defs/resourceType"
+    },
+    "resourceFieldEntry": {
+      "$ref": "plugin-manifest.schema.json#/$defs/resourceFieldEntry"
+    },
+    "resourceRequirement": {
+      "$ref": "plugin-manifest.schema.json#/$defs/resourceRequirement"
+    }
+  }
+}