@gxp-dev/tools 2.0.77 → 2.0.79

package/bin/lib/utils/ai-scaffold.js

@@ -1009,7 +1009,7 @@ function buildInteractiveInitialPrompt(projectName, description, provider) {
 		"- What real-world data it reads/writes — identify the concrete platform operationIds via the MCP, never invent them",
 		"- Which real-time events matter (use `api_find_events_for_operation` for each planned operationId)",
 		"- Every piece of admin-editable content: strings, assets, colors/thresholds/settings, feature toggles",
-		'- Whether this is a **form app** (quiz, survey, questionnaire, signup flow). If yes, set `formTemplate: true` in `app-manifest.json` and populate `configuration.json`\'s `formTemplate` root array with starter question cards (`config_add_card` with `parent_path: "/formTemplate"` — auto-initializes). See the instructions file for the full pattern. Keep end-user questions in `formTemplate` and admin config in `additionalTabs` — do not mix the two.',
+		'- Whether the plugin uses the platform\'s **form/quiz/survey API** at all. The rule has two independent parts — do not collapse them. (a) **Capability flag.** Any time the plugin calls form/quiz operationIds (creating a form, reading questions, submitting responses, listing form data), set `"formTemplate": true` in `app-manifest.json`. The platform uses this to auto-provision a `ProjectForm` for the install. Required regardless of whether you ship starter questions. (b) **Prepopulated questions.** If you want the admin to install with a starter question set instead of an empty form, also populate `configuration.json`\'s `formTemplate` root array (`config_add_card` with `parent_path: "/formTemplate"` — auto-initializes). Optional payload; the platform seeds the auto-provisioned form from it. At runtime the plugin still declares its form dependencies in `app-manifest.json` (e.g. a `quiz_form` identifier bound to `ProjectForm`) and calls `store.callApi("forms.show", "quiz_form")` / `store.callApi("form_responses.store", "quiz_form", {...})`. End-user questions go in `formTemplate`; admin plugin config stays in `additionalTabs`. Never mix.',
 		"",
 		"Then propose a plan — screens/components, data flow, admin configuration form, and the exact keys you'll add to `app-manifest.json` — and get my confirmation before implementing.",
 		"",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gxp-dev/tools",
-	"version": "2.0.77",
+	"version": "2.0.79",
 	"description": "Dev tools to create platform plugins",
 	"type": "commonjs",
 	"publishConfig": {

package/runtime/vite.config.js

@@ -313,6 +313,19 @@ export default defineConfig(async (ctx) => {
 			vue(),
 			// GxP Inspector plugin for browser extension integration
 			...(useInspector ? [gxpInspectorPlugin()] : []),
+			// `externalGlobals` rewrites `import ... from "vue"` → references to
+			// the `Vue` global that the GxP platform exposes on `window`, and
+			// `@/stores/gxpPortalConfigStore` imports → `window.useGxpStore`.
+			//
+			// We want this to run in BOTH dev and build so user source code keeps
+			// the same external-store indirection regardless of mode. The only
+			// exception is the toolkit's own runtime code (`@gxp-dev/tools/runtime/
+			// *.js` and the workspace equivalent) — that code bootstraps its own
+			// local Vue + Pinia via main.js (createApp + app.use) and would crash
+			// with "getActivePinia() was called" if its `from "pinia"` were
+			// rewritten to a non-existent `window.Pinia`.
+			//
+			// So: exclude the toolkit's runtime from the transform.
 			externalGlobals(
 				{
 					vue: "Vue",
@@ -320,11 +333,14 @@ export default defineConfig(async (ctx) => {
 					"@/stores/gxpPortalConfigStore":
 						"(window.useGxpStore || (() => { console.warn('useGxpStore not found on window, using fallback'); return {}; }))",
 				},
-				// No `include` filter — rewrite `from "vue"` / `from "pinia"`
-				// in every module of the final bundle, including transitive deps
-				// from node_modules (component libraries, etc.). Without this,
-				// deps' internal `import { h } from "vue"` leak through as bare
-				// specifiers and crash at runtime on the platform.
+				{
+					exclude: [
+						// Consumer install (published toolkit from npm)
+						"**/node_modules/@gxp-dev/tools/**",
+						// Workspace / `npm link` / self-dev: the runtime source itself
+						`${runtimeDir.replace(/\\/g, "/")}/**`,
+					],
+				},
 			),
 			// Custom request logging and CORS plugin
 			{

package/template/.claude/agents/gxp-developer.md

@@ -524,12 +524,38 @@ Every mutation is linter-guarded against `bin/lib/lint/schemas/`. If a write is
 
 ## Form / Quiz / Survey Apps — `formTemplate`
 
-Some plugins _are_ a form: a quiz, a survey, a signup flow. For those, ship a starter question set an admin can customize on install. Two keys, kept consistent:
+`formTemplate` appears in **two** files and the two meanings are **independent**. Don't collapse them — treat the manifest flag and the configuration array as separate decisions.
 
-1. **`app-manifest.json` → `"formTemplate": true`** — flags the plugin as a form app so the platform opts into form-specific UI (question editor, response viewer).
-2. **`configuration.json` → `"formTemplate": [ ...cards ]`** — array of cards defining the starter form sections, same shape as `additionalTabs`. Typically `fields_list` cards whose `fieldsList` items are the end-user questions.
+### The two keys
 
-### Minimal example
+**1. `app-manifest.json` → `"formTemplate": true` — capability flag.**
+
+Set this **any time** the plugin calls the platform's form/quiz/survey API: creating a form, reading questions, submitting responses, listing form data. It tells the platform "this plugin uses a form resource" and opts the install into form-specific behavior — auto-provisioning a `ProjectForm` for the install, enabling the question editor and response viewer in the admin UI, etc. **Required whenever form/quiz operationIds are in play, regardless of whether you ship starter questions.**
+
+**2. `configuration.json` → `"formTemplate": [ ...cards ]` — prepopulated starter questions.**
+
+An array of cards (same shape as `additionalTabs`, typically `fields_list`) that the platform seeds into the auto-provisioned `ProjectForm` at install time. **Optional** — omit it if you want the admin to build the form from scratch.
+
+### The rule — three scenarios
+
+| Scenario                                                    | Manifest `formTemplate`                                     | Configuration `formTemplate` |
+| ----------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------- |
+| Uses form/quiz API, no starter questions                    | **`true`** (required)                                       | omit                         |
+| Uses form/quiz API, with starter questions                  | **`true`** (required)                                       | `[ ...cards ]`               |
+| Doesn't touch the form/quiz API                             | omit / `false`                                              | must not be set              |
+| You have starter questions but the manifest flag is missing | — wrong: the array is dead content until the flag is `true` | —                            |
+
+In one line: **uses form API → flag is true.** **Wants to prepopulate questions → array is populated.** These are independent decisions.
+
+### How it lands at runtime
+
+1. Install-time: platform sees `formTemplate: true` in the manifest → auto-provisions a `ProjectForm` for this plugin install.
+2. If `configuration.json` has a `formTemplate` array → platform seeds that new form with those cards/questions. If absent → the form is empty and the admin fills it in.
+3. The plugin still declares its form dependencies in `app-manifest.json` (e.g. `{ "identifier": "quiz_form", "model": "ProjectForm" }`) and the admin binds that identifier to the auto-provisioned form. Plugin code then calls `store.callApi("forms.show", "quiz_form")`, `store.callApi("form_responses.store", "quiz_form", {...})`, etc.
+4. Discover the right operationIds via MCP: `api_list_tags`, then `api_list_operation_ids --tag Forms` (or `search_api_endpoints quiz`). Never invent them.
+5. After install the admin owns the form — they can add/remove/reorder questions. Your `formTemplate` is a starting point, not a lock.
+
+### Minimal example — form app with starter questions and a dependency
 
 ```json
 // app-manifest.json
@@ -540,8 +566,13 @@ Some plugins _are_ a form: a quiz, a survey, a signup flow. For those, ship a st
 	"settings": {},
 	"strings": { "default": { "title": "Welcome Quiz" } },
 	"assets": {},
-	"dependencies": [],
-	"permissions": []
+	"dependencies": [{ "identifier": "quiz_form", "model": "ProjectForm" }],
+	"permissions": [
+		{
+			"identifier": "quiz_form",
+			"description": "Read questions and submit responses"
+		}
+	]
 }
 ```
 

package/template/AGENTS.md

@@ -323,14 +323,42 @@ If a mutation is refused, read the validation error and fix the input — do not
 
 ## Form / Quiz / Survey Apps — `formTemplate`
 
-Some plugins _are_ a form — a quiz, a survey, a signup questionnaire, a check-in flow. For those, the configuration file ships a second root-level card array, `formTemplate`, that holds the starter questions an admin customizes on install.
+`formTemplate` appears in **two** places and they mean **two different things**. Read this section carefully — treat the manifest flag and the configuration array as independent decisions.
 
-**Two keys tie this together. You must set both consistently.**
+### The two keys
 
-1. **`app-manifest.json` → `"formTemplate": true`** — declares the plugin as a form app. Platforms use this to opt the install into form-specific UI (question editor, response viewer, etc.).
-2. **`configuration.json` → `"formTemplate": [ ...cards ]`** — the starter question set, structured identically to `additionalTabs`: an array of cards, typically `fields_list` sections, each with a `fieldsList` of question fields.
+**1. `app-manifest.json` → `"formTemplate": true` — the capability flag.**
 
-### Minimal example
+Set this any time the plugin calls the platform's form/quiz/survey API — creating a form, reading responses, submitting answers, listing questions. It tells the platform "this plugin owns or consumes a form resource" and opts the install into form-specific behavior (question editor in the admin UI, response viewer, auto-provisioned `ProjectForm`, etc.). **Required** whenever you're using form/quiz operationIds, regardless of whether you ship prepopulated questions.
+
+**2. `configuration.json` → `"formTemplate": [ ...cards ]` — the prepopulated questions.**
+
+A starter question set the platform seeds into the auto-provisioned form at install time, so the admin doesn't start from an empty form. Structured identically to `additionalTabs`: an array of cards (usually `fields_list`) whose `fieldsList` items are the questions. **Optional** — only set it when you actually want to ship starter content. If omitted, the platform provisions an empty form and the admin builds it from scratch.
+
+### The rule
+
+| Scenario                                                    | Manifest `formTemplate`                                        | Configuration `formTemplate` |
+| ----------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------- |
+| Plugin calls form/quiz API, ships no starter questions      | **`true`** (required)                                          | omit / leave empty           |
+| Plugin calls form/quiz API, ships starter questions         | **`true`** (required)                                          | `[ ...cards ]`               |
+| Plugin does **not** touch the form/quiz API                 | omit / `false`                                                 | must not be set              |
+| You want starter questions but didn't set the manifest flag | — fix this — the array is dead content unless the flag is true | —                            |
+
+Short version:
+
+- **Uses form/quiz API → manifest `formTemplate: true`.** Non-negotiable.
+- **Wants to prepopulate questions → configuration `formTemplate: [...]`.** Optional payload.
+
+### How the pieces connect at runtime
+
+1. At install time the platform sees `formTemplate: true` in the manifest and auto-provisions a `ProjectForm` for this plugin install.
+2. If `configuration.json` includes a `formTemplate` array, the platform seeds the new `ProjectForm` with those questions. If not, it creates an empty form.
+3. The plugin code still declares whichever form/quiz dependencies it needs in `app-manifest.json` (e.g. `quiz_form`, `response_stream`) and calls `store.callApi("forms.show", "quiz_form")` / `store.callApi("form_responses.store", "quiz_form", {...})` etc. Discover the right operationIds via the MCP (`search_api_endpoints quiz`, `api_list_operation_ids --tag Forms`).
+4. The admin can edit, add, or remove questions on the auto-provisioned form after install. Your `formTemplate` array is a starting point, not a lock — the admin owns the form once it's provisioned.
+
+So: the manifest flag wires up the form backing store; the configuration array pre-seeds its contents; the dependency bindings scope which form the plugin talks to at runtime. Three independent concerns, all of which you need for a proper form app.
+
+### Minimal example — form app with starter questions
 
 ```json
 // app-manifest.json
@@ -341,8 +369,13 @@ Some plugins _are_ a form — a quiz, a survey, a signup questionnaire, a check-
 	"settings": {},
 	"strings": { "default": { "title": "Welcome Quiz" } },
 	"assets": {},
-	"dependencies": [],
-	"permissions": []
+	"dependencies": [{ "identifier": "quiz_form", "model": "ProjectForm" }],
+	"permissions": [
+		{
+			"identifier": "quiz_form",
+			"description": "The quiz form — read questions and submit responses"
+		}
+	]
 }
 ```
 
@@ -384,12 +417,12 @@ Use the same `config_*` tools you'd use for `additionalTabs`, pointed at the `/f
 
 Use the same field types as any other form (`text`, `textarea`, `number`, `radio`, `checkbox`, `select`, `asyncSelect`, `selectAsset`, etc.). Question names live under `fieldsList[].name` — these become the response keys the platform stores.
 
-### When to use `formTemplate` vs `additionalTabs`
+### Don't confuse `formTemplate` with `additionalTabs`
 
 - `additionalTabs` — **admin** configuration form (every plugin has this). The person installing the plugin fills this in once.
 - `formTemplate` — **end-user** form questions (only form apps). Admins may tweak these before publishing; end users (attendees, staff) answer them at runtime.
 
-Don't confuse them. Strings, assets, dependencies, colors → `additionalTabs`. Quiz/survey questions that end users will answer → `formTemplate`.
+Strings, assets, dependencies, colors → `additionalTabs`. Quiz/survey questions that end users will answer → `formTemplate`.
 
 Finish with `gxdev lint --all`. The linter validates both roots against the same card/field schema, so malformed questions fail in the same way malformed admin fields do.
 

package/template/GEMINI.md

@@ -233,18 +233,36 @@ Tools: `config_list_card_types`, `config_list_field_types`, `config_get_field_sc
 
 ## Form / Quiz / Survey Apps — `formTemplate`
 
-If the plugin _is_ a form (quiz, survey, questionnaire), ship a starter question set the admin can customize on install. Two keys, both required, must be kept consistent:
+`formTemplate` lives in two files and the two meanings are independent — don't treat them as a single toggle.
 
-1. `app-manifest.json` → `"formTemplate": true` — marks the plugin as a form app.
-2. `configuration.json` → `"formTemplate": [ ...cards ]` — array of cards (same shape as `additionalTabs`), typically `fields_list` sections whose `fieldsList` items are the questions.
+### The two keys
 
-Build it with the same MCP tools, pointed at `/formTemplate`:
+- **`app-manifest.json` → `"formTemplate": true` — capability flag.** Set **any time** the plugin uses the platform's form/quiz/survey API (creating a form, reading questions, submitting responses, etc.). Tells the platform to auto-provision a `ProjectForm` for this install and opt into form-specific admin UI. Required whenever form/quiz operationIds are in play, regardless of whether you ship starter questions.
+
+- **`configuration.json` → `"formTemplate": [ ...cards ]` — prepopulated questions.** Starter question set the platform seeds into the auto-provisioned form at install time. Structured identically to `additionalTabs`. Optional — omit to let the admin build the form from scratch.
+
+### The rule
+
+- Uses form/quiz API → manifest `formTemplate: true`. Non-negotiable.
+- Wants to ship starter questions → configuration `formTemplate: [...]`. Optional payload.
+- Doesn't touch the form/quiz API → neither key.
+
+### Runtime flow
+
+1. `formTemplate: true` in the manifest → platform auto-provisions a `ProjectForm` on install.
+2. `formTemplate` array in configuration.json (if present) → seeds the new form with those starter questions.
+3. Plugin code still declares form dependencies (e.g. `quiz_form`) in `app-manifest.json` and calls `store.callApi("forms.show", "quiz_form")` / `store.callApi("form_responses.store", "quiz_form", {...})` — discover operationIds via the MCP (`search_api_endpoints quiz` / `api_list_operation_ids --tag Forms`).
+4. The admin owns the form after install; your array is a starting point, not a lock.
+
+### Building `formTemplate` with the MCP
 
 - `config_add_card` with `parent_path: "/formTemplate"` (the array is auto-initialized on first add).
 - `config_add_field` with `card_path: "/formTemplate/0"` to add questions to a section.
 - `config_list_cards` surfaces both `/additionalTabs` and `/formTemplate` cards.
 
-Mental model: `additionalTabs` = **admin** config (every plugin). `formTemplate` = **end-user** questions (only form apps). Admin strings, assets, colors, dependency bindings → `additionalTabs`. Questions an attendee/user will answer → `formTemplate`.
+### Don't confuse with `additionalTabs`
+
+`additionalTabs` = **admin** config (every plugin). `formTemplate` = **end-user** questions (only form apps). Admin strings, assets, colors, dependency bindings → `additionalTabs`. Questions an attendee/user will answer → `formTemplate`.
 
 ## Component Kit