Skip to content

Commit 85bac4b

Browse files
MarioCadenasMarioCadenas
committed
chore: poc manifest 1
1 parent c7f5fa6 commit 85bac4b

18 files changed

Lines changed: 1011 additions & 29 deletions

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,22 @@ Omit.onSetupMessage
168168

169169
***
170170

171+
### postScaffold?
172+
173+
```ts
174+
optional postScaffold: PostScaffoldStep[];
175+
```
176+
177+
Ordered steps to follow after scaffolding. Steps marked blocking must complete before proceeding.
178+
179+
#### Inherited from
180+
181+
```ts
182+
Omit.postScaffold
183+
```
184+
185+
***
186+
171187
### repository?
172188

173189
```ts

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,14 @@ Human-readable description for this field
2727

2828
***
2929

30+
### discovery?
31+
32+
```ts
33+
optional discovery: DiscoveryDescriptor;
34+
```
35+
36+
***
37+
3038
### env?
3139

3240
```ts
@@ -67,6 +75,16 @@ Named resolver prefixed by resource type (e.g., 'postgres:host'). The CLI resolv
6775

6876
***
6977

78+
### setupHint?
79+
80+
```ts
81+
optional setupHint: string;
82+
```
83+
84+
Short actionable instruction for obtaining this field's value.
85+
86+
***
87+
7088
### value?
7189

7290
```ts

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,13 @@
9595
"type": "boolean",
9696
"default": false,
9797
"description": "When true, this plugin is excluded from the template plugins manifest (appkit.plugins.json) during sync."
98+
},
99+
"postScaffold": {
100+
"type": "array",
101+
"description": "Ordered steps to follow after scaffolding. Steps marked blocking must complete before proceeding.",
102+
"items": {
103+
"$ref": "#/$defs/postScaffoldStep"
104+
}
98105
}
99106
},
100107
"additionalProperties": false,
@@ -220,6 +227,13 @@
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+
"setupHint": {
235+
"type": "string",
236+
"description": "Short actionable instruction for obtaining this field's value."
223237
}
224238
},
225239
"additionalProperties": false
@@ -405,6 +419,56 @@
405419
}
406420
]
407421
},
422+
"discoveryDescriptor": {
423+
"type": "object",
424+
"description": "How to discover candidate values for this field via CLI commands.",
425+
"required": ["cliCommand", "selectField"],
426+
"properties": {
427+
"cliCommand": {
428+
"type": "string",
429+
"description": "CLI command to list candidate values. Use <PROFILE> as a placeholder for the Databricks CLI profile."
430+
},
431+
"selectField": {
432+
"type": "string",
433+
"description": "jq-style field to extract the value from each result (e.g. '.id')."
434+
},
435+
"displayField": {
436+
"type": "string",
437+
"description": "jq-style field for human-readable display (e.g. '.name')."
438+
},
439+
"dependsOn": {
440+
"type": "string",
441+
"description": "Field name in the same resource that must be resolved first."
442+
},
443+
"shortcut": {
444+
"type": "string",
445+
"description": "Optional command that returns a single value directly instead of a list."
446+
}
447+
},
448+
"additionalProperties": false
449+
},
450+
"postScaffoldStep": {
451+
"type": "object",
452+
"description": "A single post-scaffolding step.",
453+
"required": ["step", "instruction"],
454+
"properties": {
455+
"step": {
456+
"type": "integer",
457+
"minimum": 1,
458+
"description": "Step number (sequential, starting from 1)."
459+
},
460+
"instruction": {
461+
"type": "string",
462+
"description": "What to do in this step."
463+
},
464+
"blocking": {
465+
"type": "boolean",
466+
"default": false,
467+
"description": "When true, this step must finish before proceeding to the next."
468+
}
469+
},
470+
"additionalProperties": false
471+
},
408472
"configSchemaProperty": {
409473
"type": "object",
410474
"required": ["type"],

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

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,12 @@
1212
},
1313
"version": {
1414
"type": "string",
15-
"const": "1.0",
15+
"enum": ["1.0", "1.1"],
1616
"description": "Schema version for the template plugins manifest"
1717
},
18+
"scaffolding": {
19+
"$ref": "#/$defs/scaffolding"
20+
},
1821
"plugins": {
1922
"type": "object",
2023
"description": "Map of plugin name to plugin manifest with package source",
@@ -25,6 +28,38 @@
2528
},
2629
"additionalProperties": false,
2730
"$defs": {
31+
"scaffolding": {
32+
"type": "object",
33+
"description": "Template-level metadata for constructing the scaffolding CLI command.",
34+
"required": ["command", "flags", "rules"],
35+
"properties": {
36+
"command": {
37+
"type": "string",
38+
"description": "The base CLI command for scaffolding."
39+
},
40+
"flags": {
41+
"type": "object",
42+
"description": "Map of flag name to flag descriptor.",
43+
"additionalProperties": {
44+
"type": "object",
45+
"required": ["required", "description"],
46+
"properties": {
47+
"required": { "type": "boolean" },
48+
"description": { "type": "string" },
49+
"pattern": { "type": "string" },
50+
"default": { "type": "string" }
51+
},
52+
"additionalProperties": false
53+
}
54+
},
55+
"rules": {
56+
"type": "array",
57+
"items": { "type": "string" },
58+
"description": "Rules for constructing the scaffolding command."
59+
}
60+
},
61+
"additionalProperties": false
62+
},
2863
"templatePlugin": {
2964
"type": "object",
3065
"required": [
@@ -69,6 +104,13 @@
69104
"type": "string",
70105
"description": "Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning)."
71106
},
107+
"postScaffold": {
108+
"type": "array",
109+
"description": "Ordered steps to follow after scaffolding.",
110+
"items": {
111+
"$ref": "plugin-manifest.schema.json#/$defs/postScaffoldStep"
112+
}
113+
},
72114
"resources": {
73115
"type": "object",
74116
"required": ["required", "optional"],
@@ -98,7 +140,23 @@
98140
"$ref": "plugin-manifest.schema.json#/$defs/resourceType"
99141
},
100142
"resourceFieldEntry": {
101-
"$ref": "plugin-manifest.schema.json#/$defs/resourceFieldEntry"
143+
"allOf": [
144+
{ "$ref": "plugin-manifest.schema.json#/$defs/resourceFieldEntry" },
145+
{
146+
"properties": {
147+
"resolution": {
148+
"type": "string",
149+
"enum": [
150+
"user-provided",
151+
"platform-injected",
152+
"static",
153+
"cli-resolved"
154+
],
155+
"description": "Computed during sync. Indicates how the field's value is provided: user-provided (needs --set), platform-injected (auto-set at deploy), static (has a default value), or cli-resolved (resolved by the CLI during init)."
156+
}
157+
}
158+
}
159+
]
102160
},
103161
"resourceRequirement": {
104162
"$ref": "plugin-manifest.schema.json#/$defs/resourceRequirement"

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

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,33 @@
1414
"fields": {
1515
"id": {
1616
"env": "DATABRICKS_WAREHOUSE_ID",
17-
"description": "SQL Warehouse ID"
17+
"description": "SQL Warehouse ID",
18+
"setupHint": "Run 'databricks warehouses list' to find your SQL Warehouse ID.",
19+
"discovery": {
20+
"cliCommand": "databricks warehouses list --profile <PROFILE> -o json",
21+
"selectField": ".id",
22+
"displayField": ".name",
23+
"shortcut": "databricks experimental aitools tools get-default-warehouse --profile <PROFILE>"
24+
}
1825
}
1926
}
2027
}
2128
],
2229
"optional": []
2330
},
31+
"postScaffold": [
32+
{ "step": 1, "instruction": "Create SQL query files in config/queries/" },
33+
{ "step": 2, "instruction": "Run: npm run typegen", "blocking": true },
34+
{
35+
"step": 3,
36+
"instruction": "Read client/src/appKitTypes.d.ts for generated types"
37+
},
38+
{ "step": 4, "instruction": "Write UI code using the generated types" },
39+
{
40+
"step": 5,
41+
"instruction": "Update tests/smoke.spec.ts selectors for your app"
42+
}
43+
],
2444
"config": {
2545
"schema": {
2646
"type": "object",

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

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,26 @@
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+
"setupHint": "Provide the full volume path, e.g. /Volumes/catalog/schema/volume_name.",
19+
"discovery": {
20+
"cliCommand": "databricks volumes list <catalog>.<schema> --profile <PROFILE> -o json",
21+
"selectField": ".full_name",
22+
"displayField": ".name"
23+
}
1824
}
1925
}
2026
}
2127
],
2228
"optional": []
2329
},
30+
"postScaffold": [
31+
{
32+
"step": 1,
33+
"instruction": "Use the files plugin API to read/write volume files in your tRPC procedures"
34+
},
35+
{ "step": 2, "instruction": "Build UI for file upload/download using tRPC" }
36+
],
2437
"config": {
2538
"schema": {
2639
"type": "object",

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

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,28 @@
1313
"fields": {
1414
"id": {
1515
"env": "DATABRICKS_GENIE_SPACE_ID",
16-
"description": "Default Genie Space ID"
16+
"description": "Default Genie Space ID",
17+
"setupHint": "Find your Genie Space ID in the AI/BI Genie UI."
1718
}
1819
}
1920
}
2021
],
2122
"optional": []
2223
},
24+
"postScaffold": [
25+
{
26+
"step": 1,
27+
"instruction": "Configure Genie Space aliases in the plugin config spaces map"
28+
},
29+
{
30+
"step": 2,
31+
"instruction": "Build UI components to send natural language queries via the Genie tRPC procedures"
32+
},
33+
{
34+
"step": 3,
35+
"instruction": "Update tests/smoke.spec.ts selectors for your app"
36+
}
37+
],
2338
"config": {
2439
"schema": {
2540
"type": "object",

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

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,24 @@
1515
"fields": {
1616
"branch": {
1717
"description": "Full Lakebase Postgres branch resource name. Obtain by running `databricks postgres list-branches projects/{project-id}`, select the desired item from the output array and use its .name value.",
18-
"examples": ["projects/{project-id}/branches/{branch-id}"]
18+
"examples": ["projects/{project-id}/branches/{branch-id}"],
19+
"setupHint": "Run 'databricks postgres list-branches projects/{project-id}' to find your branch.",
20+
"discovery": {
21+
"cliCommand": "databricks postgres list-branches projects/{project-id} --profile <PROFILE> -o json",
22+
"selectField": ".name"
23+
}
1924
},
2025
"database": {
2126
"description": "Full Lakebase Postgres database resource name. Obtain by running `databricks postgres list-databases {branch-name}`, select the desired item from the output array and use its .name value. Requires the branch resource name.",
2227
"examples": [
2328
"projects/{project-id}/branches/{branch-id}/databases/{database-id}"
24-
]
29+
],
30+
"setupHint": "Run 'databricks postgres list-databases {branch-name}' to find your database. Requires the branch first.",
31+
"discovery": {
32+
"cliCommand": "databricks postgres list-databases {branch} --profile <PROFILE> -o json",
33+
"selectField": ".name",
34+
"dependsOn": "branch"
35+
}
2536
},
2637
"host": {
2738
"env": "PGHOST",
@@ -60,5 +71,23 @@
6071
}
6172
],
6273
"optional": []
63-
}
74+
},
75+
"postScaffold": [
76+
{
77+
"step": 1,
78+
"instruction": "Define your schema in server/server.ts startup"
79+
},
80+
{
81+
"step": 2,
82+
"instruction": "Write tRPC procedures using pool.query() in server/server.ts"
83+
},
84+
{
85+
"step": 3,
86+
"instruction": "Build React frontend consuming tRPC procedures"
87+
},
88+
{
89+
"step": 4,
90+
"instruction": "Update tests/smoke.spec.ts selectors for your app"
91+
}
92+
]
6493
}

‎packages/appkit/src/registry/types.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export {
2929
type ResourcePermission,
3030
};
3131

32-
// Re-export generated base type from shared (schema-derived, used directly).
32+
// Re-export generated base types from shared (schema-derived, used directly).
3333
export type { ResourceFieldEntry } from "shared";
3434

3535
// Import shared base types for strict extension below.

0 commit comments

Comments
 (0)