@gxp-dev/tools 2.0.72 → 2.0.73

package/bin/lib/commands/init.js

@@ -9,8 +9,9 @@
  * 3. Run interactive configuration:
  *    - App name (prepopulated from package.json)
  *    - Description (prepopulated from package.json)
- *    - AI scaffolding (optional)
- * 4. Prompt to start the app
+ *    - SSL setup
+ *    - Launch AI agent (2nd-to-last — replaces the start-server step when chosen)
+ * 4. Start Development (skipped if an AI agent was launched)
  * 5. Prompt to launch browser with extension
  */
 
@@ -34,6 +35,7 @@ const {
 	generateSSLCertificates,
 	updateEnvWithCertPaths,
 	runAIScaffolding,
+	launchInteractiveAISession,
 	getAvailableProviders,
 } = require("../utils")
 
@@ -401,65 +403,100 @@ async function runInteractiveConfig(projectPath, initialName, isLocal = false) {
 	updatePackageJson(projectPath, appName, description)
 	updateAppManifest(projectPath, appName, description)
 
-	// 3. AI Scaffolding
+	// 3. SSL Setup
 	console.log("")
 	console.log("─".repeat(50))
-	console.log("🤖 AI-Powered Scaffolding")
+	console.log("🔒 SSL Configuration")
 	console.log("─".repeat(50))
-	console.log("   Describe what you want to build and AI will generate")
-	console.log("   starter components, views, and manifest configuration.")
+
+	const sslChoice = await arrowSelectPrompt(
+		"Set up SSL certificates for HTTPS development?",
+		[
+			{
+				label: "Yes, set up SSL",
+				value: "yes",
+				description: "Recommended for full feature access",
+			},
+			{
+				label: "Skip SSL setup",
+				value: "no",
+				description: "Can be set up later with npm run setup-ssl",
+			},
+		],
+	)
+
+	let sslSetup = false
+	if (sslChoice === "yes") {
+		console.log("\n🔒 Setting up HTTPS development environment...")
+		ensureMkcertInstalled()
+		const certs = generateSSLCertificates(projectPath)
+		if (certs) {
+			updateEnvWithCertPaths(projectPath, certs)
+			sslSetup = true
+		}
+	}
+
+	// 4. Build with an AI agent (2nd-to-last step)
+	//
+	// Launches the selected CLI in interactive mode with an initial prompt
+	// that points the agent at AGENTS.md / GEMINI.md in the scaffolded project
+	// and instructs it to greet the user, ask clarifying questions until it
+	// has enough detail, then plan and implement. When an agent is launched
+	// we skip the "Start Development" step — the agent session replaces it.
+	console.log("")
+	console.log("─".repeat(50))
+	console.log("🤖 Build with an AI Agent")
+	console.log("─".repeat(50))
+	console.log(
+		"   Launch an AI coding agent that already knows the GxP toolkit,",
+	)
+	console.log(
+		"   MCP tools, and workflow. The agent will ask you what you want",
+	)
+	console.log("   to build and then plan and implement it with you.")
 	console.log("")
 
 	// Check available AI providers
 	const providers = await getAvailableProviders()
-	const availableProviders = providers.filter((p) => p.available)
+	const interactiveProviders = providers.filter(
+		(p) => p.available && (p.id !== "gemini" || p.method === "cli"),
+	)
 
 	let aiChoice = "skip"
 	let selectedProvider = null
 
-	if (availableProviders.length === 0) {
-		console.log("   ⚠️  No AI providers available.")
-		console.log("   To enable AI scaffolding, set up one of:")
+	if (interactiveProviders.length === 0) {
+		console.log("   ⚠️  No AI CLIs detected.")
+		console.log(
+			"   To use an AI agent here, install one of the following and retry:",
+		)
 		console.log(
 			"   • Claude CLI: npm install -g @anthropic-ai/claude-code && claude login",
 		)
 		console.log("   • Codex CLI: npm install -g @openai/codex && codex auth")
 		console.log("   • Gemini CLI: npm install -g @google/gemini-cli && gemini")
-		console.log("   • Gemini API: export GEMINI_API_KEY=your_key")
 		console.log("")
 		aiChoice = "skip"
 	} else {
 		// Build provider options
-		const providerOptions = [{ label: "Skip AI scaffolding", value: "skip" }]
-
-		for (const provider of availableProviders) {
-			let authInfo = ""
-			if (provider.id === "gemini") {
-				switch (provider.method) {
-					case "cli":
-						authInfo = "logged in"
-						break
-					case "api_key":
-						authInfo = "via API key"
-						break
-					case "gcloud":
-						authInfo = "via gcloud"
-						break
-					default:
-						authInfo = ""
-				}
-			} else {
-				authInfo = "logged in"
-			}
+		const providerOptions = [
+			{
+				label: "Skip — I'll build it myself",
+				value: "skip",
+				description: "You can launch an AI agent later from the project root",
+			},
+		]
+
+		for (const provider of interactiveProviders) {
 			providerOptions.push({
-				label: `${provider.name}`,
+				label: provider.name,
 				value: provider.id,
-				description: `${authInfo}`,
+				description: "logged in",
 			})
 		}
 
 		aiChoice = await arrowSelectPrompt(
-			"Choose AI provider for scaffolding",
+			"Launch an AI agent to build your plugin?",
 			providerOptions,
 		)
 		if (aiChoice !== "skip") {
@@ -467,55 +504,17 @@ async function runInteractiveConfig(projectPath, initialName, isLocal = false) {
 		}
 	}
 
-	let buildPrompt = ""
+	// If an AI agent was chosen, it becomes the last step — skip starting the
+	// dev server. The agent is responsible for driving the rest of the session.
 	if (selectedProvider) {
-		buildPrompt = await multiLinePrompt(
-			"📝 Describe your plugin (what it does, key features, UI elements):",
-			"Press Enter twice when done",
+		await launchInteractiveAISession(
+			projectPath,
+			appName,
+			description,
+			selectedProvider,
 		)
-
-		if (buildPrompt) {
-			await runAIScaffolding(
-				projectPath,
-				appName,
-				description,
-				buildPrompt,
-				selectedProvider,
-			)
-		}
-	}
-
-	// 4. SSL Setup
-	console.log("")
-	console.log("─".repeat(50))
-	console.log("🔒 SSL Configuration")
-	console.log("─".repeat(50))
-
-	const sslChoice = await arrowSelectPrompt(
-		"Set up SSL certificates for HTTPS development?",
-		[
-			{
-				label: "Yes, set up SSL",
-				value: "yes",
-				description: "Recommended for full feature access",
-			},
-			{
-				label: "Skip SSL setup",
-				value: "no",
-				description: "Can be set up later with npm run setup-ssl",
-			},
-		],
-	)
-
-	let sslSetup = false
-	if (sslChoice === "yes") {
-		console.log("\n🔒 Setting up HTTPS development environment...")
-		ensureMkcertInstalled()
-		const certs = generateSSLCertificates(projectPath)
-		if (certs) {
-			updateEnvWithCertPaths(projectPath, certs)
-			sslSetup = true
-		}
+		printFinalInstructions(projectPath, appName, sslSetup, isLocal)
+		return null
 	}
 
 	// 5. Start App

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,
 }

package/mcp/gxp-api-server.js

@@ -63,12 +63,40 @@ function searchEndpoints(spec, query) {
 }
 
 /**
- * Search AsyncAPI spec for channels/events matching a query
+ * Search AsyncAPI spec for channels/events matching a query.
+ *
+ * Matches across:
+ *   - components.messages (event name, summary, description, x-triggered-by)
+ *   - channels            (channel name, description)
+ *
+ * For messages, the returned `eventName` is what you pass to
+ * store.listen(eventName, permissionIdentifier, callback) on the client.
  */
 function searchEvents(spec, query) {
 	const results = []
 	const queryLower = query.toLowerCase()
 
+	const messages = spec?.components?.messages || {}
+	for (const [eventName, message] of Object.entries(messages)) {
+		if (typeof message !== "object" || message === null) continue
+		const trigger = message["x-triggered-by"] || ""
+		if (
+			eventName.toLowerCase().includes(queryLower) ||
+			message.summary?.toLowerCase().includes(queryLower) ||
+			message.description?.toLowerCase().includes(queryLower) ||
+			trigger.toLowerCase().includes(queryLower)
+		) {
+			results.push({
+				kind: "event",
+				eventName,
+				summary: message.summary || "",
+				description: message.description || "",
+				triggeredBy: trigger || null,
+				payloadRef: message.payload?.$ref || null,
+			})
+		}
+	}
+
 	if (spec.channels) {
 		for (const [channel, details] of Object.entries(spec.channels)) {
 			if (
@@ -92,6 +120,7 @@ function searchEvents(spec, query) {
 				}
 
 				results.push({
+					kind: "channel",
 					channel,
 					description: details.description || "",
 					operations,
@@ -200,7 +229,7 @@ const API_TOOLS = [
 	{
 		name: "search_websocket_events",
 		description:
-			"Search for WebSocket channels/events matching a query. Searches channel names and descriptions.",
+			"Search AsyncAPI events matching a query. Searches components.messages (event name, summary, description, x-triggered-by) and channel definitions. The returned eventName is what you pass to store.listen(eventName, permissionIdentifier, callback).",
 		inputSchema: {
 			type: "object",
 			properties: {

package/mcp/lib/api-tools.js

@@ -158,6 +158,38 @@ const EXT_API_TOOLS = [
 			required: [],
 		},
 	},
+	{
+		name: "api_find_events_for_operation",
+		description:
+			"Given an OpenAPI operationId, return every AsyncAPI message whose x-triggered-by matches. Use this after adding a callApi(operationId, ...) call to discover whether a socket event is fired server-side — subscribe to it with store.listen(eventName, permissionIdentifier, cb) instead of polling.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				operationId: {
+					type: "string",
+					description:
+						"OpenAPI operationId (e.g. 'posts.store'). Bare ids and 'portal.v1.project.<id>' are both accepted.",
+				},
+			},
+			required: ["operationId"],
+		},
+	},
+	{
+		name: "api_list_events",
+		description:
+			"List all AsyncAPI events from components.messages. Each entry includes the event name, summary/description, and x-triggered-by (if declared). Optionally filter by triggeredBy operationId.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				triggeredBy: {
+					type: "string",
+					description:
+						"Only return events whose x-triggered-by equals this operationId. Omit for all events.",
+				},
+			},
+			required: [],
+		},
+	},
 	{
 		name: "api_generate_dependency",
 		description:
@@ -312,6 +344,50 @@ async function findEndpointsBySchema(filters) {
 	return out
 }
 
+function normalizeOperationId(id) {
+	if (!id) return id
+	return id.replace(/^portal\.v1\.project\./, "")
+}
+
+async function listAsyncApiEvents(triggeredBy) {
+	const spec = await fetchSpec("asyncapi")
+	const messages = spec?.components?.messages || {}
+	const targetTrigger = triggeredBy ? normalizeOperationId(triggeredBy) : null
+
+	const out = []
+	for (const [eventName, message] of Object.entries(messages)) {
+		if (typeof message !== "object" || message === null) continue
+		const trigger = message["x-triggered-by"] || null
+		if (targetTrigger && normalizeOperationId(trigger) !== targetTrigger) {
+			continue
+		}
+		out.push({
+			eventName,
+			summary: message.summary || "",
+			description: message.description || "",
+			triggeredBy: trigger,
+			payloadRef: message.payload?.$ref || null,
+		})
+	}
+	return out
+}
+
+async function findEventsForOperation(operationId) {
+	if (!operationId) {
+		return { ok: false, error: "operationId is required" }
+	}
+	const events = await listAsyncApiEvents(operationId)
+	return {
+		ok: true,
+		operationId: normalizeOperationId(operationId),
+		events,
+		note:
+			events.length === 0
+				? "No AsyncAPI messages declare x-triggered-by for this operationId. Either the operation does not fire a platform event, or the spec has not declared the trigger yet."
+				: "Subscribe with store.listen(eventName, permissionIdentifier, callback) to receive these events live.",
+	}
+}
+
 async function generateDependency({
 	identifier,
 	tag,
@@ -429,6 +505,14 @@ async function handleExtApiToolCall(name, args = {}) {
 				results: await findEndpointsBySchema(args || {}),
 			})
 
+		case "api_find_events_for_operation":
+			return contentResult(await findEventsForOperation(args.operationId))
+
+		case "api_list_events":
+			return contentResult({
+				events: await listAsyncApiEvents(args.triggeredBy),
+			})
+
 		case "api_generate_dependency":
 			return contentResult(await generateDependency(args))
 
@@ -453,4 +537,7 @@ module.exports = {
 	getOperationParameters,
 	findEndpointsBySchema,
 	generateDependency,
+	listAsyncApiEvents,
+	findEventsForOperation,
+	normalizeOperationId,
 }

package/package.json

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