Skip to content

Commit 0d5addb

Browse files
MarioCadenasMarioCadenas
committed
chore: poc manifest 2
1 parent c7f5fa6 commit 0d5addb

20 files changed

Lines changed: 1386 additions & 54 deletions

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

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,13 @@
9191
"type": "string",
9292
"description": "Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning)."
9393
},
94+
"postScaffold": {
95+
"type": "array",
96+
"description": "Ordered guidance for human or agent follow-up after scaffolding.",
97+
"items": {
98+
"$ref": "#/$defs/postScaffoldStep"
99+
}
100+
},
94101
"hidden": {
95102
"type": "boolean",
96103
"default": false,
@@ -220,10 +227,53 @@
220227
"type": "string",
221228
"pattern": "^[a-z_]+:[a-zA-Z]+$",
222229
"description": "Named resolver prefixed by resource type (e.g., 'postgres:host'). The CLI resolves this value during the init prompt flow."
230+
},
231+
"discovery": {
232+
"$ref": "#/$defs/discoveryDescriptor"
233+
},
234+
"resolution": {
235+
"$ref": "#/$defs/resourceResolution"
223236
}
224237
},
225238
"additionalProperties": false
226239
},
240+
"discoveryDescriptor": {
241+
"type": "object",
242+
"required": ["cliCommand", "selectField"],
243+
"properties": {
244+
"cliCommand": {
245+
"type": "string",
246+
"minLength": 1,
247+
"description": "CLI command to list candidate values. Use <PROFILE> as a placeholder for the Databricks CLI profile."
248+
},
249+
"selectField": {
250+
"type": "string",
251+
"minLength": 1,
252+
"description": "jq-style selector for the machine-readable value to capture from the CLI output."
253+
},
254+
"displayField": {
255+
"type": "string",
256+
"minLength": 1,
257+
"description": "jq-style selector for a human-readable label to display alongside the selected value."
258+
},
259+
"dependsOn": {
260+
"type": "string",
261+
"minLength": 1,
262+
"description": "Field name in the same resource that must be resolved before running this discovery command."
263+
},
264+
"shortcut": {
265+
"type": "string",
266+
"minLength": 1,
267+
"description": "Optional direct CLI command that returns a single preferred value."
268+
}
269+
},
270+
"additionalProperties": false
271+
},
272+
"resourceResolution": {
273+
"type": "string",
274+
"enum": ["user-provided", "platform-injected"],
275+
"description": "How this field's value is supplied to the app."
276+
},
227277
"resourceRequirement": {
228278
"type": "object",
229279
"description": "Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements().",
@@ -405,6 +455,28 @@
405455
}
406456
]
407457
},
458+
"postScaffoldStep": {
459+
"type": "object",
460+
"required": ["step", "instruction"],
461+
"properties": {
462+
"step": {
463+
"type": "integer",
464+
"minimum": 1,
465+
"description": "Step number in the ordered post-scaffold flow."
466+
},
467+
"instruction": {
468+
"type": "string",
469+
"minLength": 1,
470+
"description": "Instruction to follow after scaffolding completes."
471+
},
472+
"blocking": {
473+
"type": "boolean",
474+
"default": false,
475+
"description": "When true, this step must finish before continuing."
476+
}
477+
},
478+
"additionalProperties": false
479+
},
408480
"configSchemaProperty": {
409481
"type": "object",
410482
"required": ["type"],

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

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://databricks.github.io/appkit/schemas/template-plugins.schema.v2.json",
4+
"title": "AppKit Template Plugins Manifest V2",
5+
"description": "Aggregated plugin manifest for AppKit templates. Read by Databricks CLI during init to discover available plugins, resource requirements, and scaffold guidance.",
6+
"type": "object",
7+
"required": ["version", "scaffolding", "plugins"],
8+
"properties": {
9+
"$schema": {
10+
"type": "string",
11+
"description": "Reference to the JSON Schema for validation"
12+
},
13+
"version": {
14+
"type": "string",
15+
"const": "2.0",
16+
"description": "Schema version for the template plugins manifest"
17+
},
18+
"scaffolding": {
19+
"$ref": "#/$defs/scaffolding"
20+
},
21+
"plugins": {
22+
"type": "object",
23+
"description": "Map of plugin name to plugin manifest with package source",
24+
"additionalProperties": {
25+
"$ref": "#/$defs/templatePlugin"
26+
}
27+
}
28+
},
29+
"additionalProperties": false,
30+
"$defs": {
31+
"templatePlugin": {
32+
"type": "object",
33+
"required": [
34+
"name",
35+
"displayName",
36+
"description",
37+
"package",
38+
"resources"
39+
],
40+
"description": "Plugin manifest with package source information",
41+
"properties": {
42+
"name": {
43+
"type": "string",
44+
"pattern": "^[a-z][a-z0-9-]*$",
45+
"description": "Plugin identifier. Must be lowercase, start with a letter, and contain only letters, numbers, and hyphens.",
46+
"examples": ["analytics", "server", "my-custom-plugin"]
47+
},
48+
"displayName": {
49+
"type": "string",
50+
"minLength": 1,
51+
"description": "Human-readable display name for UI and CLI",
52+
"examples": ["Analytics Plugin", "Server Plugin"]
53+
},
54+
"description": {
55+
"type": "string",
56+
"minLength": 1,
57+
"description": "Brief description of what the plugin does",
58+
"examples": ["SQL query execution against Databricks SQL Warehouses"]
59+
},
60+
"package": {
61+
"type": "string",
62+
"minLength": 1,
63+
"description": "NPM package name or relative path that provides this plugin",
64+
"examples": ["@databricks/appkit", "./plugins/custom-plugin"]
65+
},
66+
"requiredByTemplate": {
67+
"type": "boolean",
68+
"default": false,
69+
"description": "When true, this plugin is required by the template and cannot be deselected during CLI init."
70+
},
71+
"onSetupMessage": {
72+
"type": "string",
73+
"description": "Human-facing message displayed after project initialization to explain manual setup steps."
74+
},
75+
"postScaffold": {
76+
"type": "array",
77+
"description": "Ordered follow-up guidance for a human or agent after scaffolding.",
78+
"items": {
79+
"$ref": "plugin-manifest.schema.json#/$defs/postScaffoldStep"
80+
}
81+
},
82+
"resources": {
83+
"type": "object",
84+
"required": ["required", "optional"],
85+
"description": "Databricks resource requirements for this plugin",
86+
"properties": {
87+
"required": {
88+
"type": "array",
89+
"description": "Resources that must be available for the plugin to function",
90+
"items": {
91+
"$ref": "#/$defs/resourceRequirement"
92+
}
93+
},
94+
"optional": {
95+
"type": "array",
96+
"description": "Resources that enhance functionality but are not mandatory",
97+
"items": {
98+
"$ref": "#/$defs/resourceRequirement"
99+
}
100+
}
101+
},
102+
"additionalProperties": false
103+
}
104+
},
105+
"additionalProperties": false
106+
},
107+
"scaffoldingFlag": {
108+
"type": "object",
109+
"required": ["required", "description"],
110+
"properties": {
111+
"required": {
112+
"type": "boolean"
113+
},
114+
"description": {
115+
"type": "string",
116+
"minLength": 1
117+
},
118+
"pattern": {
119+
"type": "string",
120+
"minLength": 1
121+
},
122+
"default": {
123+
"type": "string"
124+
}
125+
},
126+
"additionalProperties": false
127+
},
128+
"scaffolding": {
129+
"type": "object",
130+
"required": ["command", "flags", "rules"],
131+
"properties": {
132+
"command": {
133+
"type": "string",
134+
"minLength": 1
135+
},
136+
"flags": {
137+
"type": "object",
138+
"minProperties": 1,
139+
"additionalProperties": {
140+
"$ref": "#/$defs/scaffoldingFlag"
141+
}
142+
},
143+
"rules": {
144+
"type": "array",
145+
"items": {
146+
"type": "string",
147+
"minLength": 1
148+
}
149+
}
150+
},
151+
"additionalProperties": false
152+
},
153+
"resourceType": {
154+
"$ref": "plugin-manifest.schema.json#/$defs/resourceType"
155+
},
156+
"resourceFieldEntry": {
157+
"$ref": "plugin-manifest.schema.json#/$defs/resourceFieldEntry"
158+
},
159+
"resourceRequirement": {
160+
"$ref": "plugin-manifest.schema.json#/$defs/resourceRequirement"
161+
}
162+
}
163+
}

‎packages/appkit/src/plugins/analytics/manifest.json‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,14 @@
1414
"fields": {
1515
"id": {
1616
"env": "DATABRICKS_WAREHOUSE_ID",
17-
"description": "SQL Warehouse ID"
17+
"description": "SQL Warehouse ID",
18+
"discovery": {
19+
"cliCommand": "databricks warehouses list --profile <PROFILE> -o json",
20+
"selectField": ".id",
21+
"displayField": ".name",
22+
"shortcut": "databricks experimental aitools tools get-default-warehouse --profile <PROFILE>"
23+
},
24+
"resolution": "user-provided"
1825
}
1926
}
2027
}
@@ -32,5 +39,29 @@
3239
}
3340
}
3441
}
35-
}
42+
},
43+
"onSetupMessage": "Run 'databricks warehouses list' to find your SQL Warehouse ID.",
44+
"postScaffold": [
45+
{
46+
"step": 1,
47+
"instruction": "Create SQL query files in config/queries/"
48+
},
49+
{
50+
"step": 2,
51+
"instruction": "Run: npm run typegen",
52+
"blocking": true
53+
},
54+
{
55+
"step": 3,
56+
"instruction": "Read client/src/appKitTypes.d.ts for generated types"
57+
},
58+
{
59+
"step": 4,
60+
"instruction": "Write UI code using the generated types"
61+
},
62+
{
63+
"step": 5,
64+
"instruction": "Update tests/smoke.spec.ts selectors for your app"
65+
}
66+
]
3667
}

‎packages/appkit/src/plugins/files/manifest.json‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,13 @@
1414
"fields": {
1515
"path": {
1616
"env": "DATABRICKS_VOLUME_FILES",
17-
"description": "Volume path for file storage (e.g. /Volumes/catalog/schema/volume_name)"
17+
"description": "Volume path for file storage (e.g. /Volumes/catalog/schema/volume_name)",
18+
"discovery": {
19+
"cliCommand": "databricks volumes list <CATALOG> <SCHEMA> --profile <PROFILE> -o json",
20+
"selectField": ".full_name",
21+
"displayField": ".name"
22+
},
23+
"resolution": "user-provided"
1824
}
1925
}
2026
}
@@ -37,5 +43,16 @@
3743
}
3844
}
3945
}
40-
}
46+
},
47+
"onSetupMessage": "Provide the full volume path, e.g. /Volumes/catalog/schema/volume_name.",
48+
"postScaffold": [
49+
{
50+
"step": 1,
51+
"instruction": "Use the files plugin API to read/write volume files in your tRPC procedures"
52+
},
53+
{
54+
"step": 2,
55+
"instruction": "Build UI for file upload/download using tRPC"
56+
}
57+
]
4158
}

‎packages/appkit/src/plugins/genie/manifest.json‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
{
2+
"$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
23
"name": "genie",
34
"displayName": "Genie Plugin",
45
"description": "AI/BI Genie space integration for natural language data queries",
@@ -13,7 +14,13 @@
1314
"fields": {
1415
"id": {
1516
"env": "DATABRICKS_GENIE_SPACE_ID",
16-
"description": "Default Genie Space ID"
17+
"description": "Default Genie Space ID",
18+
"discovery": {
19+
"cliCommand": "databricks genie list-spaces --profile <PROFILE> -o json",
20+
"selectField": ".space_id",
21+
"displayField": ".title"
22+
},
23+
"resolution": "user-provided"
1724
}
1825
}
1926
}
@@ -39,5 +46,24 @@
3946
},
4047
"required": ["spaces"]
4148
}
42-
}
49+
},
50+
"onSetupMessage": "Find your Genie Space ID in the AI/BI Genie UI.",
51+
"postScaffold": [
52+
{
53+
"step": 1,
54+
"instruction": "Configure your Genie space aliases in server setup or rely on the default space ID"
55+
},
56+
{
57+
"step": 2,
58+
"instruction": "Build a chat UI with GenieChat or useGenieChat against your chosen alias"
59+
},
60+
{
61+
"step": 3,
62+
"instruction": "Wire your app routes and page navigation to the Genie experience"
63+
},
64+
{
65+
"step": 4,
66+
"instruction": "Update tests/smoke.spec.ts selectors for your app"
67+
}
68+
]
4369
}

0 commit comments

Comments
 (0)