feat: add plugin commands (#110)

Author: MarioCadenas

CLAUDE.md

@@ -95,6 +95,17 @@ pnpm check:fix        # Auto-fix with Biome
 pnpm typecheck        # TypeScript type checking across all packages
 ```
 
+### AppKit CLI
+When using the published SDK or running from the monorepo (after `pnpm build`), the `appkit` CLI is available:
+
+```bash
+npx appkit plugin sync --write    # Sync plugin manifests into appkit.plugins.json
+npx appkit plugin create         # Scaffold a new plugin (interactive, uses @clack/prompts)
+npx appkit plugin validate       # Validate manifest(s) against the JSON schema
+npx appkit plugin list           # List plugins (from appkit.plugins.json or --dir)
+npx appkit plugin add-resource   # Add a resource requirement to a plugin (interactive)
+```
+
 ### Deployment
 ```bash
 pnpm pack:sdk                      # Package SDK for deployment

CONTRIBUTING.md

@@ -112,3 +112,24 @@ pnpm docs:serve  # Serve built docs
 ```
 
 See [docs/README.md](./docs/README.md) for more details.
+
+## Adding or changing a resource type
+
+Resource types and their permissions are defined once in the plugin-manifest schema; the CLI (create, add-resource, validate) and the appkit registry types are derived from it.
+
+To add or change a resource type:
+
+1. **Edit the schema** – `packages/shared/src/schemas/plugin-manifest.schema.json`:
+   - Add the value to `$defs.resourceType.enum`.
+   - Add a permission definition (e.g. `$defs.myResourcePermission`) with an `enum` array; list permissions **weakest to strongest** (this order is used for merge/escalation).
+   - In `$defs.resourceRequirement.allOf`, add a branch with `if.properties.type.const` set to the new type and `then.properties.permission.$ref` pointing at that permission def (e.g. `#/$defs/myResourcePermission`).
+
+2. **Regenerate registry types** – from the repo root:
+   ```bash
+   pnpm exec tsx tools/generate-registry-types.ts
+   ```
+   This updates `packages/appkit/src/registry/types.generated.ts`. The appkit build runs this automatically before compiling.
+
+3. **Optional:** Add default fields for the new type in `packages/shared/src/cli/commands/plugin/create/resource-defaults.ts` (`DEFAULT_FIELDS_BY_TYPE`) so the plugin create/add-resource prompts suggest env vars.
+
+For more context and alternative approaches, see [Registry types from schema](./docs/docs/development/registry-types-from-schema.md).

docs/docs/api/appkit/Enumeration.ResourceType.md

@@ -1,7 +1,6 @@
 # Enumeration: ResourceType
 
-Supported resource types that plugins can depend on.
-Each type has its own set of valid permissions.
+Resource types from schema $defs.resourceType.enum
 
 ## Enumeration Members
 
@@ -11,8 +10,6 @@ Each type has its own set of valid permissions.
 APP: "app";
 ```
 
-Databricks App dependency
-
 ***
 
 ### DATABASE
@@ -21,8 +18,6 @@ Databricks App dependency
 DATABASE: "database";
 ```
 
-Database (Lakebase) for persistent storage
-
 ***
 
 ### EXPERIMENT
@@ -31,8 +26,6 @@ Database (Lakebase) for persistent storage
 EXPERIMENT: "experiment";
 ```
 
-MLflow Experiment for ML tracking
-
 ***
 
 ### GENIE\_SPACE
@@ -41,8 +34,6 @@ MLflow Experiment for ML tracking
 GENIE_SPACE: "genie_space";
 ```
 
-Genie Space for AI assistant
-
 ***
 
 ### JOB
@@ -51,8 +42,6 @@ Genie Space for AI assistant
 JOB: "job";
 ```
 
-Databricks Job for scheduled or triggered workflows
-
 ***
 
 ### SECRET
@@ -61,8 +50,6 @@ Databricks Job for scheduled or triggered workflows
 SECRET: "secret";
 ```
 
-Secret scope for secure credential storage
-
 ***
 
 ### SERVING\_ENDPOINT
@@ -71,8 +58,6 @@ Secret scope for secure credential storage
 SERVING_ENDPOINT: "serving_endpoint";
 ```
 
-Model serving endpoint for ML inference
-
 ***
 
 ### SQL\_WAREHOUSE
@@ -81,8 +66,6 @@ Model serving endpoint for ML inference
 SQL_WAREHOUSE: "sql_warehouse";
 ```
 
-Databricks SQL Warehouse for query execution
-
 ***
 
 ### UC\_CONNECTION
@@ -91,8 +74,6 @@ Databricks SQL Warehouse for query execution
 UC_CONNECTION: "uc_connection";
 ```
 
-Unity Catalog Connection for external data sources
-
 ***
 
 ### UC\_FUNCTION
@@ -101,8 +82,6 @@ Unity Catalog Connection for external data sources
 UC_FUNCTION: "uc_function";
 ```
 
-Unity Catalog Function
-
 ***
 
 ### VECTOR\_SEARCH\_INDEX
@@ -111,14 +90,10 @@ Unity Catalog Function
 VECTOR_SEARCH_INDEX: "vector_search_index";
 ```
 
-Vector Search Index for similarity search
-
 ***
 
 ### VOLUME
 
 ```ts
 VOLUME: "volume";
 ```
-
-Unity Catalog Volume for file storage

docs/docs/api/appkit/TypeAlias.ToPlugin.md

@@ -0,0 +1,23 @@
+# Type Alias: ToPlugin()\<T, U, N\>
+
+```ts
+type ToPlugin<T, U, N> = (config?: U) => PluginData<T, U, N>;
+```
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+| `U` |
+| `N` *extends* `string` |
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `config?` | `U` |
+
+## Returns
+
+`PluginData`\<`T`, `U`, `N`\>

docs/docs/api/appkit/index.md

@@ -8,7 +8,7 @@ plugin architecture, and React integration.
 | Enumeration | Description |
 | ------ | ------ |
 | [RequestedClaimsPermissionSet](Enumeration.RequestedClaimsPermissionSet.md) | Permission set for Unity Catalog table access |
-| [ResourceType](Enumeration.ResourceType.md) | Supported resource types that plugins can depend on. Each type has its own set of valid permissions. |
+| [ResourceType](Enumeration.ResourceType.md) | Resource types from schema $defs.resourceType.enum |
 
 ## Classes
 
@@ -53,6 +53,7 @@ plugin architecture, and React integration.
 | [ConfigSchema](TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
 | [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
 | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
+| [ToPlugin](TypeAlias.ToPlugin.md) | - |
 
 ## Variables
 

docs/docs/api/appkit/typedoc-sidebar.ts

@@ -177,6 +177,11 @@ const typedocSidebar: SidebarsConfig = {
           type: "doc",
           id: "api/appkit/TypeAlias.ResourcePermission",
           label: "ResourcePermission"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.ToPlugin",
+          label: "ToPlugin"
         }
       ]
     },

docs/docs/plugins.md

@@ -205,9 +205,97 @@ const AppKit = await createApp({
 
 For complete configuration options, see [`createApp`](api/appkit/Function.createApp.md).
 
+## Plugin management
+
+AppKit includes a CLI for managing plugins. All commands are available under `npx @databricks/appkit plugin`.
+
+### Create a plugin
+
+Scaffold a new plugin interactively:
+
+```bash
+npx @databricks/appkit plugin create
+```
+
+The wizard walks you through:
+- **Placement**: In your repository (e.g. `plugins/my-plugin`) or as a standalone package
+- **Metadata**: Name, display name, description
+- **Resources**: Which Databricks resources the plugin needs (SQL Warehouse, Secret, etc.) and whether each is required or optional
+- **Optional fields**: Author, version, license
+
+The command generates a complete plugin scaffold with `manifest.json`, TypeScript class, and barrel exports — ready to register in your app.
+
+### Sync plugin manifests
+
+Scan your project for plugins and generate `appkit.plugins.json`:
+
+```bash
+npx @databricks/appkit plugin sync --write
+```
+
+This discovers plugin manifests from installed packages and local imports, then writes a consolidated manifest used by deployment tooling. Plugins referenced in your `createApp({ plugins: [...] })` call are automatically marked as required.
+
+Use the `--silent` flag in build hooks to suppress output:
+
+```json
+{
+  "scripts": {
+    "sync": "appkit plugin sync --write --silent",
+    "predev": "npm run sync",
+    "prebuild": "npm run sync"
+  }
+}
+```
+
+### Validate manifests
+
+Check plugin manifests against the JSON schema:
+
+```bash
+# Validate manifest.json in the current directory
+npx @databricks/appkit plugin validate
+
+# Validate specific files or directories
+npx @databricks/appkit plugin validate plugins/my-plugin appkit.plugins.json
+```
+
+The validator auto-detects whether a file is a plugin manifest or a template manifest (from `$schema`) and reports errors with humanized paths and expected values.
+
+### List plugins
+
+View registered plugins from `appkit.plugins.json` or scan a directory:
+
+```bash
+# From appkit.plugins.json (default)
+npx @databricks/appkit plugin list
+
+# Scan a directory for plugin folders
+npx @databricks/appkit plugin list --dir plugins/
+
+# JSON output for scripting
+npx @databricks/appkit plugin list --json
+```
+
+### Add a resource to a plugin
+
+Interactively add a new resource requirement to an existing plugin manifest:
+
+```bash
+npx @databricks/appkit plugin add-resource
+
+# Or specify the plugin directory
+npx @databricks/appkit plugin add-resource --path plugins/my-plugin
+```
+
 ## Creating custom plugins
 
-If you need custom API routes or background logic, implement an AppKit plugin.
+If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
+
+```bash
+npx @databricks/appkit plugin create
+```
+
+For a deeper understanding of the plugin structure, read on.
 
 ### Basic plugin example