@databricks/appkit-ui 0.8.0 → 0.9.0

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"
+    }
+  }
+}