chore: poc manifest 3

Author: MarioCadenas

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

@@ -168,6 +168,22 @@ Omit.onSetupMessage
 
 ***
 
+### postScaffold?
+
+```ts
+optional postScaffold: PostScaffoldStep[];
+```
+
+Ordered follow-up steps that a user or agent should perform after scaffolding.
+
+#### Inherited from
+
+```ts
+Omit.postScaffold
+```
+
+***
+
 ### repository?
 
 ```ts

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

@@ -0,0 +1,5 @@
+# Type Alias: ResourceFieldEntry
+
+```ts
+type ResourceFieldEntry = GeneratedResourceFieldEntry;
+```

docs/docs/api/appkit/TypeAlias.ResourceFieldEntry.md

@@ -40,7 +40,6 @@ plugin architecture, and React integration.
 | [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(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union. |
 | [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. |
 | [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications |
@@ -53,6 +52,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 |
 | [PluginData](TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. |
+| [ResourceFieldEntry](TypeAlias.ResourceFieldEntry.md) | - |
 | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
 | [ToPlugin](TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. |
 

docs/docs/api/appkit/index.md

@@ -132,11 +132,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.ResourceEntry",
           label: "ResourceEntry"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.ResourceFieldEntry",
-          label: "ResourceFieldEntry"
-        },
         {
           type: "doc",
           id: "api/appkit/Interface.ResourceRequirement",
@@ -178,6 +173,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.PluginData",
           label: "PluginData"
         },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.ResourceFieldEntry",
+          label: "ResourceFieldEntry"
+        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.ResourcePermission",

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

@@ -91,6 +91,13 @@
       "type": "string",
       "description": "Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning)."
     },
+    "postScaffold": {
+      "type": "array",
+      "description": "Ordered follow-up steps that a user or agent should perform after scaffolding.",
+      "items": {
+        "$ref": "#/$defs/postScaffoldStep"
+      }
+    },
     "hidden": {
       "type": "boolean",
       "default": false,
@@ -197,6 +204,12 @@
           "type": "string",
           "description": "Human-readable description for this field"
         },
+        "discovery": {
+          "$ref": "#/$defs/discoveryDescriptor"
+        },
+        "resolution": {
+          "$ref": "#/$defs/resourceResolution"
+        },
         "bundleIgnore": {
           "type": "boolean",
           "default": false,
@@ -224,6 +237,65 @@
       },
       "additionalProperties": false
     },
+    "discoveryDescriptor": {
+      "type": "object",
+      "required": ["cliCommand", "selectField"],
+      "properties": {
+        "cliCommand": {
+          "type": "string",
+          "minLength": 1,
+          "description": "CLI command to list candidate values. Use <PROFILE> as a placeholder for the Databricks CLI profile."
+        },
+        "selectField": {
+          "type": "string",
+          "minLength": 1,
+          "description": "jq-style field used to extract the machine-readable value from each command result."
+        },
+        "displayField": {
+          "type": "string",
+          "minLength": 1,
+          "description": "jq-style field used to extract a human-readable display value from each command result."
+        },
+        "dependsOn": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Field name in the same resource that must be resolved before running this discovery command."
+        },
+        "shortcut": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional shortcut command that returns a single value directly."
+        }
+      },
+      "additionalProperties": false
+    },
+    "resourceResolution": {
+      "type": "string",
+      "enum": ["user-provided", "platform-injected"],
+      "description": "Indicates whether the value must be supplied by the user/agent or is injected automatically by the platform."
+    },
+    "postScaffoldStep": {
+      "type": "object",
+      "required": ["step", "instruction"],
+      "properties": {
+        "step": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based step number in the post-scaffold flow."
+        },
+        "instruction": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Instruction to follow after scaffolding."
+        },
+        "blocking": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, this step must be completed before proceeding."
+        }
+      },
+      "additionalProperties": false
+    },
     "resourceRequirement": {
       "type": "object",
       "description": "Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements().",

docs/static/schemas/plugin-manifest.schema.json

@@ -12,9 +12,12 @@
     },
     "version": {
       "type": "string",
-      "const": "1.0",
+      "enum": ["1.0", "2.0"],
       "description": "Schema version for the template plugins manifest"
     },
+    "scaffolding": {
+      "$ref": "#/$defs/scaffolding"
+    },
     "plugins": {
       "type": "object",
       "description": "Map of plugin name to plugin manifest with package source",
@@ -23,6 +26,19 @@
       }
     }
   },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "version": { "const": "2.0" }
+        },
+        "required": ["version"]
+      },
+      "then": {
+        "required": ["scaffolding"]
+      }
+    }
+  ],
   "additionalProperties": false,
   "$defs": {
     "templatePlugin": {
@@ -69,6 +85,13 @@
           "type": "string",
           "description": "Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning)."
         },
+        "postScaffold": {
+          "type": "array",
+          "description": "Ordered follow-up steps that a user or agent should perform after scaffolding.",
+          "items": {
+            "$ref": "plugin-manifest.schema.json#/$defs/postScaffoldStep"
+          }
+        },
         "resources": {
           "type": "object",
           "required": ["required", "optional"],
@@ -94,6 +117,52 @@
       },
       "additionalProperties": false
     },
+    "scaffoldingFlag": {
+      "type": "object",
+      "required": ["required", "description"],
+      "properties": {
+        "required": {
+          "type": "boolean"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pattern": {
+          "type": "string",
+          "minLength": 1
+        },
+        "default": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "scaffolding": {
+      "type": "object",
+      "required": ["command", "flags", "rules"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "minLength": 1
+        },
+        "flags": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "$ref": "#/$defs/scaffoldingFlag"
+          }
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "resourceType": {
       "$ref": "plugin-manifest.schema.json#/$defs/resourceType"
     },

docs/static/schemas/template-plugins.schema.json

@@ -3,6 +3,30 @@
   "name": "analytics",
   "displayName": "Analytics Plugin",
   "description": "SQL query execution against Databricks SQL Warehouses",
+  "onSetupMessage": "Run 'databricks warehouses list' to find your SQL Warehouse ID.",
+  "postScaffold": [
+    {
+      "step": 1,
+      "instruction": "Create SQL query files in config/queries/"
+    },
+    {
+      "step": 2,
+      "instruction": "Run: npm run typegen",
+      "blocking": true
+    },
+    {
+      "step": 3,
+      "instruction": "Read client/src/appKitTypes.d.ts for generated types"
+    },
+    {
+      "step": 4,
+      "instruction": "Write UI code using the generated types"
+    },
+    {
+      "step": 5,
+      "instruction": "Update tests/smoke.spec.ts selectors for your app"
+    }
+  ],
   "resources": {
     "required": [
       {
@@ -14,7 +38,14 @@
         "fields": {
           "id": {
             "env": "DATABRICKS_WAREHOUSE_ID",
-            "description": "SQL Warehouse ID"
+            "description": "SQL Warehouse ID",
+            "discovery": {
+              "cliCommand": "databricks warehouses list --profile <PROFILE> -o json",
+              "selectField": ".id",
+              "displayField": ".name",
+              "shortcut": "databricks experimental aitools tools get-default-warehouse --profile <PROFILE>"
+            },
+            "resolution": "user-provided"
           }
         }
       }