Skip to content

Commit a835f5e

Browse files
MarioCadenasMarioCadenas
committed
chore: poc manifest 2
1 parent 832111b commit a835f5e

File tree

19 files changed

+1381
-52
lines changed

19 files changed

+1381
-52
lines changed

‎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,
@@ -219,10 +226,53 @@
219226
"type": "string",
220227
"pattern": "^[a-z_]+:[a-zA-Z]+$",
221228
"description": "Named resolver prefixed by resource type (e.g., 'postgres:host'). The CLI resolves this value during the init prompt flow."
229+
},
230+
"discovery": {
231+
"$ref": "#/$defs/discoveryDescriptor"
232+
},
233+
"resolution": {
234+
"$ref": "#/$defs/resourceResolution"
222235
}
223236
},
224237
"additionalProperties": false
225238
},
239+
"discoveryDescriptor": {
240+
"type": "object",
241+
"required": ["cliCommand", "selectField"],
242+
"properties": {
243+
"cliCommand": {
244+
"type": "string",
245+
"minLength": 1,
246+
"description": "CLI command to list candidate values. Use <PROFILE> as a placeholder for the Databricks CLI profile."
247+
},
248+
"selectField": {
249+
"type": "string",
250+
"minLength": 1,
251+
"description": "jq-style selector for the machine-readable value to capture from the CLI output."
252+
},
253+
"displayField": {
254+
"type": "string",
255+
"minLength": 1,
256+
"description": "jq-style selector for a human-readable label to display alongside the selected value."
257+
},
258+
"dependsOn": {
259+
"type": "string",
260+
"minLength": 1,
261+
"description": "Field name in the same resource that must be resolved before running this discovery command."
262+
},
263+
"shortcut": {
264+
"type": "string",
265+
"minLength": 1,
266+
"description": "Optional direct CLI command that returns a single preferred value."
267+
}
268+
},
269+
"additionalProperties": false
270+
},
271+
"resourceResolution": {
272+
"type": "string",
273+
"enum": ["user-provided", "platform-injected"],
274+
"description": "How this field's value is supplied to the app."
275+
},
226276
"resourceRequirement": {
227277
"type": "object",
228278
"required": ["type", "alias", "resourceKey", "description", "permission"],
@@ -403,6 +453,28 @@
403453
}
404454
]
405455
},
456+
"postScaffoldStep": {
457+
"type": "object",
458+
"required": ["step", "instruction"],
459+
"properties": {
460+
"step": {
461+
"type": "integer",
462+
"minimum": 1,
463+
"description": "Step number in the ordered post-scaffold flow."
464+
},
465+
"instruction": {
466+
"type": "string",
467+
"minLength": 1,
468+
"description": "Instruction to follow after scaffolding completes."
469+
},
470+
"blocking": {
471+
"type": "boolean",
472+
"default": false,
473+
"description": "When true, this step must finish before continuing."
474+
}
475+
},
476+
"additionalProperties": false
477+
},
406478
"configSchemaProperty": {
407479
"type": "object",
408480
"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)