@gxp-dev/tools 2.0.71 → 2.0.73

package/bin/lib/lint/schemas/common.schema.json

@@ -0,0 +1,62 @@
+{
+	"$id": "https://gxp.dev/schemas/common.schema.json",
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "GxP Common Definitions",
+	"description": "Shared sub-schemas referenced by card and field schemas.",
+	"$defs": {
+		"conditionParam": {
+			"type": "object",
+			"properties": {
+				"name": { "type": "string" },
+				"value": {
+					"type": ["string", "number", "boolean", "null"]
+				},
+				"logic": {
+					"type": "string",
+					"enum": ["==", "!=", ">", ">=", "<", "<=", "in", "not_in", "includes"]
+				},
+				"column": { "type": ["string", "null"] }
+			},
+			"required": ["name", "logic"],
+			"additionalProperties": true
+		},
+		"conditionParams": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/conditionParam" }
+		},
+		"gridCols": {
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 12
+		},
+		"colorHex": {
+			"type": "string",
+			"pattern": "^#(?:[0-9a-fA-F]{3}){1,2}$"
+		},
+		"urlOrPath": {
+			"type": "string",
+			"description": "Absolute URL or site-relative path",
+			"pattern": "^(https?:)?(//)?/?[^\\s]*$"
+		},
+		"identifier": {
+			"type": "string",
+			"pattern": "^[A-Za-z_][A-Za-z0-9_-]*$"
+		},
+		"option": {
+			"type": "object",
+			"properties": {
+				"label": { "type": "string" },
+				"value": {
+					"type": ["string", "number", "boolean", "null"]
+				},
+				"disabled": { "type": "boolean" }
+			},
+			"required": ["label", "value"],
+			"additionalProperties": true
+		},
+		"options": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/option" }
+		}
+	}
+}

package/bin/lib/lint/schemas/configuration.schema.json

@@ -0,0 +1,19 @@
+{
+	"$id": "https://gxp.dev/schemas/configuration.schema.json",
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "GxP Plugin Configuration Form",
+	"description": "Defines the configuration form shown to admins in the GxP admin panel when they install or configure a plugin. Follows the GxP templating system (ShowPage > tabs > cards > fields).",
+	"type": "object",
+	"required": ["additionalTabs"],
+	"properties": {
+		"additionalTabs": {
+			"type": "array",
+			"description": "Top-level array of tab definitions. Each item is a card (usually card_list or fields_list) rendered under the plugin's configuration panel.",
+			"items": { "$ref": "card.schema.json" }
+		},
+		"title": { "type": ["string", "null"] },
+		"description": { "type": ["string", "null"] },
+		"version": { "type": ["string", "integer", "null"] }
+	},
+	"additionalProperties": true
+}

package/bin/lib/lint/schemas/field.schema.json

@@ -0,0 +1,230 @@
+{
+	"$id": "https://gxp.dev/schemas/field.schema.json",
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "GxP Form Field",
+	"description": "A single form field descriptor used inside a fields_list card.",
+	"type": "object",
+	"required": ["type"],
+	"properties": {
+		"type": {
+			"type": "string",
+			"enum": [
+				"hidden",
+				"html",
+				"live-html",
+				"heading",
+				"heading-large",
+				"small-heading",
+				"description",
+				"image",
+				"video",
+				"icon",
+				"icon-selector",
+				"clipboard",
+				"timestamp",
+				"button",
+				"external_link",
+				"text",
+				"number",
+				"email",
+				"password",
+				"phone_number",
+				"textarea",
+				"select",
+				"pill_select",
+				"multi_select",
+				"autocomplete",
+				"asyncSelect",
+				"radio",
+				"checkbox",
+				"boolean",
+				"boolean_icon",
+				"file",
+				"selectAsset",
+				"selectPagePlugin",
+				"selectProjectPlan",
+				"keyValuePair",
+				"codeEditor",
+				"htmlEditor",
+				"render_markdown",
+				"colorPicker",
+				"tag_list",
+				"savedSearchBuilder",
+				"date",
+				"datetime",
+				"time",
+				"timezone_picker",
+				"data_table",
+				"integration_connector",
+				"form-builder",
+				"object-builder"
+			],
+			"description": "Field type. Determines which extra properties are required."
+		},
+		"name": { "type": ["string", "null"] },
+		"label": { "type": ["string", "null"] },
+		"default": {
+			"type": ["string", "number", "boolean", "array", "object", "null"]
+		},
+		"placeholder": { "type": ["string", "null"] },
+		"disabled": { "type": "boolean" },
+		"readonly": { "type": "boolean" },
+		"required": { "type": "boolean" },
+		"multiple": { "type": "boolean" },
+		"classList": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"columnClass": { "type": ["string", "null"] },
+		"cols": {
+			"$ref": "common.schema.json#/$defs/gridCols"
+		},
+		"colsSm": { "$ref": "common.schema.json#/$defs/gridCols" },
+		"colsMd": { "$ref": "common.schema.json#/$defs/gridCols" },
+		"colsLg": { "$ref": "common.schema.json#/$defs/gridCols" },
+		"condition": { "type": ["string", "null"] },
+		"conditionParams": {
+			"$ref": "common.schema.json#/$defs/conditionParams"
+		},
+		"content": { "type": ["string", "null"] },
+		"text": { "type": ["string", "null"] },
+		"href": { "type": ["string", "null"] },
+		"icon": { "type": ["string", "null"] },
+		"options": {
+			"$ref": "common.schema.json#/$defs/options"
+		},
+		"accept": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"format": { "type": ["string", "null"] },
+		"prepend": { "type": ["string", "null"] },
+		"append": { "type": ["string", "null"] },
+		"method": {
+			"type": ["string", "null"],
+			"enum": ["GET", "POST", "PUT", "PATCH", "DELETE", null]
+		},
+		"query_parameter": { "type": ["string", "null"] },
+		"refresh": {
+			"type": "object",
+			"properties": {
+				"only": { "type": "string" },
+				"key": { "type": "string" }
+			},
+			"additionalProperties": true
+		},
+		"validation_rules": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"custom_settings": { "type": "object" }
+	},
+	"allOf": [
+		{
+			"if": {
+				"properties": {
+					"type": {
+						"enum": [
+							"select",
+							"pill_select",
+							"multi_select",
+							"radio",
+							"checkbox"
+						]
+					}
+				},
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["options"],
+				"properties": {
+					"options": {
+						"$ref": "common.schema.json#/$defs/options",
+						"minItems": 1
+					}
+				}
+			}
+		},
+		{
+			"if": {
+				"properties": {
+					"type": {
+						"enum": [
+							"text",
+							"number",
+							"email",
+							"password",
+							"phone_number",
+							"textarea",
+							"select",
+							"pill_select",
+							"multi_select",
+							"autocomplete",
+							"asyncSelect",
+							"radio",
+							"checkbox",
+							"boolean",
+							"boolean_icon",
+							"file",
+							"selectAsset",
+							"keyValuePair",
+							"codeEditor",
+							"htmlEditor",
+							"colorPicker",
+							"tag_list",
+							"date",
+							"datetime",
+							"time",
+							"timezone_picker"
+						]
+					}
+				},
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["name"],
+				"properties": {
+					"name": {
+						"type": "string",
+						"minLength": 1
+					}
+				}
+			}
+		},
+		{
+			"if": {
+				"properties": { "type": { "const": "asyncSelect" } },
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["href", "method"]
+			}
+		},
+		{
+			"if": {
+				"properties": { "type": { "const": "external_link" } },
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["href"]
+			}
+		},
+		{
+			"if": {
+				"properties": { "type": { "const": "colorPicker" } },
+				"required": ["type"]
+			},
+			"then": {
+				"properties": {
+					"default": {
+						"oneOf": [
+							{ "$ref": "common.schema.json#/$defs/colorHex" },
+							{ "type": "null" }
+						]
+					}
+				}
+			}
+		}
+	],
+	"additionalProperties": true
+}

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

@@ -953,6 +953,141 @@ async function runAIScaffolding(
 	return result.errors.length === 0
 }
 
+/**
+ * Build the initial prompt sent to an interactive AI CLI session.
+ * The prompt anchors the agent in the scaffolded project, points it at
+ * the project's instruction files (which describe the full tool set),
+ * and tells it to keep asking questions until it has enough detail.
+ *
+ * @param {string} projectName - Plugin name
+ * @param {string} description - Plugin description
+ * @param {string} provider - Selected AI provider (claude, codex, gemini)
+ * @returns {string} Prompt text
+ */
+function buildInteractiveInitialPrompt(projectName, description, provider) {
+	const instructionFile = provider === "gemini" ? "GEMINI.md" : "AGENTS.md"
+	const claudeAgentHint =
+		provider === "claude"
+			? " You can also delegate to the `gxp-developer` subagent defined in `.claude/agents/gxp-developer.md`."
+			: ""
+
+	return [
+		`I just ran \`gxdev init\` to scaffold a new GxP plugin called "${projectName}"${
+			description ? ` (${description})` : ""
+		} in this directory.`,
+		"",
+		`Start a new GxP plugin development session. First read \`${instructionFile}\` and \`app-instructions.md\` in this project — they describe the workflow, conventions, and the full set of tools available to you.${claudeAgentHint}`,
+		"",
+		"You have the `gxp-api` MCP server available with 29 tools across five families:",
+		"- **API spec discovery** — `search_api_endpoints`, `api_list_operation_ids`, `api_get_operation_parameters`, `api_find_endpoints_by_schema`, `api_generate_dependency`, `get_endpoint_details`.",
+		"- **WebSocket events** — `api_find_events_for_operation` (maps an operationId to the AsyncAPI events it triggers), `api_list_events`, `search_websocket_events`.",
+		"- **Config editing** — `config_add_card`, `config_add_field`, `config_list_field_types`, `config_get_field_schema`, `config_extract_strings`, `config_validate`, etc. Every mutation is linter-guarded against the schemas in `bin/lib/lint/schemas/`.",
+		"- **Docs search** — `docs_search`, `docs_get_page`, `docs_list_pages` (full-text search across docs.gxp.dev).",
+		"- **Test helpers** — `test_scaffold_component_test`, `test_api_route`.",
+		"",
+		"Follow the full workflow from the instructions: (1) understand the feature, (2) discover data sources via MCP, (3) plan including the admin configuration form, (4) implement, (5) **sync the manifest and build the admin form**, (6) test with real broadcasts, (7) final `gxdev lint --all`.",
+		"",
+		"Step 5 is not optional. Every time you add or change a `store.callApi`, `store.listen`, `gxp-string`, or `gxp-src`, close the loop:",
+		'- Call `config_extract_strings` with `writeTo: "app-manifest.json"` — it scans `src/` and merges every directive, store getter, and dependency identifier into the manifest (same logic as `gxdev extract-config`, linter-guarded).',
+		"- For every entry now in the manifest, add a matching field in `configuration.json` using the MCP `config_*` tools. Default mapping: `strings.default.*` → `text`/`textarea`, `assets.*` → `selectAsset`, each declared `dependencies[]` identifier → `asyncSelect` bound to the resource's list endpoint, colors → `colorPicker`, numbers → `number`, toggles → `boolean`. Field `name` must match the manifest key exactly.",
+		"- Run `gxdev lint --all` before moving on.",
+		"",
+		"Do NOT start implementing until you have enough detail. Keep asking me clarifying questions until you know:",
+		"- The user-facing outcome and who uses it (attendee, staff, admin)",
+		"- 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",
+		"",
+		"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.",
+		"",
+		"Begin now by greeting me briefly and asking what I want to build. Ask one focused question at a time rather than dumping a full questionnaire.",
+	].join("\n")
+}
+
+/**
+ * Launch the selected AI CLI in interactive mode with an initial prompt.
+ * The user talks to the agent directly in the terminal; the agent is
+ * responsible for eliciting the feature spec and building it.
+ *
+ * @param {string} projectPath - Project directory (cwd for the spawned CLI)
+ * @param {string} projectName - Plugin name
+ * @param {string} description - Plugin description
+ * @param {string} provider - claude | codex | gemini
+ * @returns {Promise<boolean>} True if the CLI exited successfully
+ */
+function launchInteractiveAISession(
+	projectPath,
+	projectName,
+	description,
+	provider,
+) {
+	return new Promise((resolve) => {
+		const initialPrompt = buildInteractiveInitialPrompt(
+			projectName,
+			description,
+			provider,
+		)
+
+		let command
+		let args
+
+		switch (provider) {
+			case "claude":
+				command = "claude"
+				args = [initialPrompt]
+				break
+			case "codex":
+				command = "codex"
+				args = [initialPrompt]
+				break
+			case "gemini":
+				command = "gemini"
+				args = ["-i", initialPrompt]
+				break
+			default:
+				console.error(
+					`❌ Interactive AI sessions are not supported for provider: ${provider}`,
+				)
+				resolve(false)
+				return
+		}
+
+		console.log("")
+		console.log("─".repeat(50))
+		console.log(`🚀 Launching ${provider} in interactive mode...`)
+		console.log("─".repeat(50))
+		console.log("")
+		console.log(
+			"   The agent will read this project's instruction files, greet you,",
+		)
+		console.log(
+			"   and ask what you want to build. Answer its questions — it will",
+		)
+		console.log(
+			"   keep asking until it has enough detail, then plan, confirm, and",
+		)
+		console.log("   implement. Exit the agent when you're done.")
+		console.log("")
+
+		const child = spawn(command, args, {
+			cwd: projectPath,
+			stdio: "inherit",
+			shell: true,
+		})
+
+		child.on("close", (code) => {
+			console.log("")
+			console.log(`✅ ${provider} session ended.`)
+			resolve(code === 0)
+		})
+
+		child.on("error", (err) => {
+			console.error(`❌ Failed to launch ${provider}: ${err.message}`)
+			resolve(false)
+		})
+	})
+}
+
 module.exports = {
 	SCAFFOLD_SYSTEM_PROMPT,
 	AI_PROVIDERS,
@@ -961,4 +1096,6 @@ module.exports = {
 	applyScaffold,
 	generateScaffold,
 	runAIScaffolding,
+	buildInteractiveInitialPrompt,
+	launchInteractiveAISession,
 }