refactor: generate plugin types from JSON Schema

Eliminate three hand-maintained copies of ResourceFieldEntry,
ResourceRequirement, and PluginManifest by generating TypeScript
interfaces from plugin-manifest.schema.json using
json-schema-to-typescript.

- Add tools/generate-schema-types.ts for schema→TS generation
- shared/plugin.ts imports and extends generated types
- manifest-types.ts re-exports from generated types
- appkit/registry/types.ts narrows type→ResourceType enum,
  permission→ResourcePermission union
- Add generate:types root script and CI drift check
- Keep custom script for ResourceType enum, permission hierarchies

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>

Author: pkosiec

.github/workflows/ci.yml

@@ -50,6 +50,18 @@ jobs:
           cache: 'pnpm'
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
+      - name: Check generated types are up to date
+        run: |
+          pnpm run generate:types
+          if ! git diff --exit-code packages/shared/src/schemas/plugin-manifest.generated.ts packages/appkit/src/registry/types.generated.ts; then
+            echo "❌ Error: Generated types are out of sync with plugin-manifest.schema.json."
+            echo ""
+            echo "To fix this:"
+            echo "  1. Run: pnpm run generate:types"
+            echo "  2. Review and commit the changes"
+            echo ""
+            exit 1
+          fi
       - name: Run Biome Check
         run: pnpm run check
       - name: Run Types Check

docs/docs/api/appkit/Interface.PluginManifest.md

@@ -1,7 +1,11 @@
 # Interface: PluginManifest\<TName\>
 
 Plugin manifest that declares metadata and resource requirements.
-Attached to plugin classes as a static property.
+Extends the shared PluginManifest with strict resource types.
+
+## Extends
+
+- `Omit`\<`SharedPluginManifest`, `"resources"` \| `"config"`\>
 
 ## Type Parameters
 
@@ -17,7 +21,13 @@ Attached to plugin classes as a static property.
 optional author: string;
 ```
 
-Optional metadata for community plugins
+Author name or organization
+
+#### Inherited from
+
+```ts
+Omit.author
+```
 
 ***
 
@@ -30,7 +40,7 @@ optional config: {
 ```
 
 Configuration schema for the plugin.
-Defines the shape and validation rules for plugin config.
+Uses JSONSchema7 instead of the generated ConfigSchema (which is too restrictive).
 
 #### schema
 
@@ -48,6 +58,12 @@ description: string;
 
 Brief description of what the plugin does
 
+#### Inherited from
+
+```ts
+Omit.description
+```
+
 ***
 
 ### displayName
@@ -56,7 +72,13 @@ Brief description of what the plugin does
 displayName: string;
 ```
 
-Human-readable display name for UI/CLI
+Human-readable display name for UI and CLI
+
+#### Inherited from
+
+```ts
+Omit.displayName
+```
 
 ***
 
@@ -66,7 +88,13 @@ Human-readable display name for UI/CLI
 optional hidden: boolean;
 ```
 
-When true, excluded from the template plugins manifest during sync.
+When true, this plugin is excluded from the template plugins manifest (appkit.plugins.json) during sync.
+
+#### Inherited from
+
+```ts
+Omit.hidden
+```
 
 ***
 
@@ -76,6 +104,14 @@ When true, excluded from the template plugins manifest during sync.
 optional keywords: string[];
 ```
 
+Keywords for plugin discovery
+
+#### Inherited from
+
+```ts
+Omit.keywords
+```
+
 ***
 
 ### license?
@@ -84,6 +120,14 @@ optional keywords: string[];
 optional license: string;
 ```
 
+SPDX license identifier
+
+#### Inherited from
+
+```ts
+Omit.license
+```
+
 ***
 
 ### name
@@ -94,6 +138,28 @@ name: TName;
 
 Plugin identifier — the single source of truth for the plugin's name
 
+#### Overrides
+
+```ts
+Omit.name
+```
+
+***
+
+### onSetupMessage?
+
+```ts
+optional onSetupMessage: string;
+```
+
+Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning).
+
+#### Inherited from
+
+```ts
+Omit.onSetupMessage
+```
+
 ***
 
 ### repository?
@@ -102,6 +168,14 @@ Plugin identifier — the single source of truth for the plugin's name
 optional repository: string;
 ```
 
+URL to the plugin's source repository
+
+#### Inherited from
+
+```ts
+Omit.repository
+```
+
 ***
 
 ### resources
@@ -113,7 +187,7 @@ resources: {
 };
 ```
 
-Resource requirements declaration
+Resource requirements declaration (with strict ResourceRequirement types)
 
 #### optional
 
@@ -138,3 +212,11 @@ Resources that must be available for the plugin to function
 ```ts
 optional version: string;
 ```
+
+Plugin version (semver format)
+
+#### Inherited from
+
+```ts
+Omit.version
+```

docs/docs/api/appkit/Interface.ResourceEntry.md

@@ -15,7 +15,7 @@ Extends ResourceRequirement with resolution state and plugin ownership.
 alias: string;
 ```
 
-Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display.
+Human-readable label for UI/display only. Deduplication uses resourceKey, not alias.
 
 #### Inherited from
 
@@ -43,8 +43,7 @@ Human-readable description of why this resource is needed
 fields: Record<string, ResourceFieldEntry>;
 ```
 
-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.
+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).
 
 #### Inherited from
 
@@ -58,7 +57,7 @@ Single-value types use one key (e.g. id); multi-value (database, secret) use mul
 permission: ResourcePermission;
 ```
 
-Required permission level for the resource
+Required permission level for the resource (narrowed to union)
 
 #### Inherited from
 
@@ -94,8 +93,6 @@ Plugin(s) that require this resource (comma-separated if multiple)
 required: boolean;
 ```
 
-Whether this resource is required (true) or optional (false)
-
 #### Inherited from
 
 [`ResourceRequirement`](Interface.ResourceRequirement.md).[`required`](Interface.ResourceRequirement.md#required)
@@ -118,7 +115,7 @@ Whether the resource has been resolved (all field env vars set)
 resourceKey: string;
 ```
 
-Stable key for machine use (env naming, composite keys, app.yaml). Required.
+Stable key for machine use: deduplication, env naming, composite keys, app.yaml. Required for registry lookup.
 
 #### Inherited from
 
@@ -132,7 +129,7 @@ Stable key for machine use (env naming, composite keys, app.yaml). Required.
 type: ResourceType;
 ```
 
-Type of Databricks resource required
+Type of Databricks resource required (narrowed to enum)
 
 #### Inherited from
 

docs/docs/api/appkit/Interface.ResourceFieldEntry.md

@@ -1,8 +1,5 @@
 # Interface: ResourceFieldEntry
 
-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).
-
 ## Properties
 
 ### bundleIgnore?

docs/docs/api/appkit/Interface.ResourceRequirement.md

@@ -1,7 +1,11 @@
 # Interface: ResourceRequirement
 
 Declares a resource requirement for a plugin.
-Can be defined statically in a manifest or dynamically via getResourceRequirements().
+Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union.
+
+## Extends
+
+- `ResourceRequirement`
 
 ## Extended by
 
@@ -15,7 +19,13 @@ Can be defined statically in a manifest or dynamically via getResourceRequiremen
 alias: string;
 ```
 
-Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display.
+Human-readable label for UI/display only. Deduplication uses resourceKey, not alias.
+
+#### Inherited from
+
+```ts
+SharedResourceRequirement.alias
+```
 
 ***
 
@@ -27,6 +37,12 @@ description: string;
 
 Human-readable description of why this resource is needed
 
+#### Inherited from
+
+```ts
+SharedResourceRequirement.description
+```
+
 ***
 
 ### fields
@@ -35,8 +51,13 @@ Human-readable description of why this resource is needed
 fields: Record<string, ResourceFieldEntry>;
 ```
 
-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.
+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).
+
+#### Inherited from
+
+```ts
+SharedResourceRequirement.fields
+```
 
 ***
 
@@ -46,7 +67,13 @@ Single-value types use one key (e.g. id); multi-value (database, secret) use mul
 permission: ResourcePermission;
 ```
 
-Required permission level for the resource
+Required permission level for the resource (narrowed to union)
+
+#### Overrides
+
+```ts
+SharedResourceRequirement.permission
+```
 
 ***
 
@@ -56,7 +83,11 @@ Required permission level for the resource
 required: boolean;
 ```
 
-Whether this resource is required (true) or optional (false)
+#### Inherited from
+
+```ts
+SharedResourceRequirement.required
+```
 
 ***
 
@@ -66,7 +97,13 @@ Whether this resource is required (true) or optional (false)
 resourceKey: string;
 ```
 
-Stable key for machine use (env naming, composite keys, app.yaml). Required.
+Stable key for machine use: deduplication, env naming, composite keys, app.yaml. Required for registry lookup.
+
+#### Inherited from
+
+```ts
+SharedResourceRequirement.resourceKey
+```
 
 ***
 
@@ -76,4 +113,10 @@ Stable key for machine use (env naming, composite keys, app.yaml). Required.
 type: ResourceType;
 ```
 
-Type of Databricks resource required
+Type of Databricks resource required (narrowed to enum)
+
+#### Overrides
+
+```ts
+SharedResourceRequirement.type
+```

docs/docs/api/appkit/index.md

@@ -36,12 +36,12 @@ plugin architecture, and React integration.
 | [GenerateDatabaseCredentialRequest](Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials |
 | [ITelemetry](Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
 | [LakebasePoolConfig](Interface.LakebasePoolConfig.md) | Configuration for creating a Lakebase connection pool |
-| [PluginManifest](Interface.PluginManifest.md) | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. |
+| [PluginManifest](Interface.PluginManifest.md) | Plugin manifest that declares metadata and resource requirements. Extends the shared PluginManifest with strict resource types. |
 | [RequestedClaims](Interface.RequestedClaims.md) | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables |
 | [RequestedResource](Interface.RequestedResource.md) | Resource to request permissions for in Unity Catalog |
 | [ResourceEntry](Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
-| [ResourceFieldEntry](Interface.ResourceFieldEntry.md) | 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). |
-| [ResourceRequirement](Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). |
+| [ResourceFieldEntry](Interface.ResourceFieldEntry.md) | - |
+| [ResourceRequirement](Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union. |
 | [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Configuration for streaming execution with default and user-scoped settings |
 | [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications |
 | [ValidationResult](Interface.ValidationResult.md) | Result of validating all registered resources against the environment. |