@gxp-dev/tools 2.0.72 → 2.0.74

package/bin/gx-devtools.js

@@ -1,118 +1,90 @@
 #!/usr/bin/env node
 
 /**
- * GxToolkit CLI
+ * GxToolkit CLI dispatcher.
  *
- * This tool works both as a globally installed npm package and as a local dependency.
- * It provides commands for creating new GxP projects and managing development workflows.
+ * Default mode is the plain CLI. The interactive Terminal UI (TUI) only
+ * launches when the user either runs `gxdev ui` or passes `--ui` alongside
+ * another command. Running `gxdev` with no command prints the help menu.
  *
- * Commands:
- *   (no command)    - Launch interactive TUI (Terminal UI)
- *   init [name]     - Initialize a new GxP project or update existing one
- *   setup-ssl       - Setup SSL certificates for HTTPS development
- *   dev             - Start development server (launches TUI with auto-start)
- *   build           - Build plugin for production
- *   publish [file]  - Publish package files to local project
- *   datastore       - Manage GxP datastore
- *   socket          - Simulate socket events (launches TUI with auto-start)
- *   assets          - Manage development assets and placeholders
- *   ext:firefox     - Launch Firefox with browser extension (launches TUI)
- *   ext:chrome      - Launch Chrome with browser extension (launches TUI)
- *   ext:build       - Build browser extensions for distribution
+ * Launching into the TUI still supports auto-starting well-known long-running
+ * commands (dev, socket, ext:chrome, ext:firefox) so that `gxdev dev --ui`
+ * boots the TUI with the dev server already running.
  */
 
-// Commands that should use the traditional CLI (one-shot commands)
-const ONE_SHOT_COMMANDS = [
-	"init",
-	"build",
-	"publish",
-	"setup-ssl",
-	"ext:build",
-	"add-dependency",
-	"extract-config",
-	"--help",
-	"-h",
-	"--version",
-]
-
-// Commands that should launch TUI with auto-start
-const TUI_AUTO_START_COMMANDS = [
-	"dev",
-	"socket",
-	"ext:firefox",
-	"ext:chrome",
-	"datastore",
-	"assets",
-]
-
 const args = process.argv.slice(2)
 const command = args[0]
 
-// Check if this is a one-shot command
-const isOneShot =
-	ONE_SHOT_COMMANDS.includes(command) || (command && command.startsWith("-"))
-
-// Check if we should use TUI with auto-start
-const isTuiCommand = TUI_AUTO_START_COMMANDS.includes(command)
+// TUI activation: bare `ui` command OR any invocation with `--ui`.
+const uiFlagPresent = args.includes("--ui")
+const isBareUiCommand = command === "ui"
+const wantsUi = uiFlagPresent || isBareUiCommand
 
-// --cli flag forces non-TUI mode regardless of TTY
-const forceCliMode = args.includes("--cli")
+if (!wantsUi) {
+	// Default path — delegate straight to yargs-driven CLI.
+	require("./lib/cli")
+	return
+}
 
-// If no command or TUI command, try to launch TUI
-// Fall back to traditional CLI if TUI dependencies are not available
-if (!isOneShot) {
-	const fs = require("fs")
-	const path = require("path")
-	// TUI output is in project root's dist/tui, not bin/dist/tui
-	const tuiPath = path.join(__dirname, "..", "dist", "tui", "index.js")
+// TUI path — locate the compiled TUI bundle and hand off.
+const fs = require("fs")
+const path = require("path")
+const tuiPath = path.join(__dirname, "..", "dist", "tui", "index.js")
 
-	// Check if we're in an interactive terminal (TTY); fall back to CLI if not
-	const isTTY = process.stdout.isTTY && process.stdin.isTTY
+if (!fs.existsSync(tuiPath)) {
+	console.error("TUI bundle not found.")
+	console.error('Run "npm run build:tui" in gx-devtools to compile it.')
+	process.exit(1)
+}
 
-	if (fs.existsSync(tuiPath) && isTTY && !forceCliMode) {
-		// Use dynamic import() for ESM modules (ink v5 is ESM-only)
-		;(async () => {
-			try {
-				const { startTUI } = await import(tuiPath)
+const isTTY = process.stdout.isTTY && process.stdin.isTTY
+if (!isTTY) {
+	console.error(
+		"The GxP TUI requires an interactive terminal (TTY). Run the plain CLI form without --ui.",
+	)
+	process.exit(1)
+}
 
-				// Determine auto-start commands
-				const autoStart = []
-				const tuiArgs = {}
+// Work out which TUI services to auto-start from the command that was paired
+// with --ui. `gxdev ui` on its own launches the TUI idle.
+const autoStart = []
+const tuiArgs = {}
 
-				if (command === "dev") {
-					autoStart.push("dev")
-					if (args.includes("--with-socket") || args.includes("-s")) {
-						autoStart.push("socket")
-					}
-					tuiArgs.noHttps = args.includes("--no-https")
-				} else if (command === "socket") {
-					autoStart.push("socket")
-				} else if (command === "ext:firefox") {
-					autoStart.push("ext firefox")
-				} else if (command === "ext:chrome") {
-					autoStart.push("ext chrome")
-				}
+switch (isBareUiCommand ? null : command) {
+	case "dev":
+		autoStart.push("dev")
+		if (args.includes("--with-socket") || args.includes("-s")) {
+			autoStart.push("socket")
+		}
+		tuiArgs.noHttps = args.includes("--no-https")
+		break
+	case "socket":
+		autoStart.push("socket")
+		break
+	case "ext:firefox":
+		autoStart.push("ext firefox")
+		break
+	case "ext:chrome":
+		autoStart.push("ext chrome")
+		break
+	default:
+		// No known auto-start for this command (or no command) — launch idle.
+		break
+}
 
-				startTUI({ autoStart, args: tuiArgs })
-			} catch (err) {
-				// TUI not available or no TTY — fall back to traditional CLI
-				if (err.message !== "NO_TTY") {
-					console.error("TUI error:", err.message)
-				}
-				require("./lib/cli")
-			}
-		})()
-	} else if (!isTTY || forceCliMode) {
-		// Non-interactive shell or --cli flag — skip TUI and run directly
-		require("./lib/cli")
-	} else {
-		// TUI not compiled yet, use traditional CLI
-		console.log(
-			'Note: TUI not yet available. Run "npm run build:tui" to enable interactive mode.',
+;(async () => {
+	try {
+		const { startTUI } = await import(tuiPath)
+		startTUI({ autoStart, args: tuiArgs })
+	} catch (err) {
+		if (err && err.message === "NO_TTY") {
+			console.error("The GxP TUI requires an interactive terminal (TTY).")
+			process.exit(1)
+		}
+		console.error(
+			"Failed to start TUI:",
+			err && err.message ? err.message : err,
 		)
-		require("./lib/cli")
+		process.exit(1)
 	}
-} else {
-	// One-shot command, use traditional CLI
-	require("./lib/cli")
-}
+})()

package/bin/lib/cli.js

@@ -31,12 +31,42 @@ const {
 const globalConfig = loadGlobalConfig()
 
 // Set up yargs CLI
-yargs
-	.usage("$0 <command>")
+const cli = yargs
+	.scriptName("gxdev")
+	.usage(
+		[
+			"Usage: gxdev <command> [options]",
+			"",
+			"By default every command runs in the plain CLI. Pass --ui to any",
+			"command to launch it inside the interactive Terminal UI, or run",
+			"`gxdev ui` to open the TUI without starting anything.",
+		].join("\n"),
+	)
 	.config(globalConfig)
+	.option("ui", {
+		describe:
+			"Launch the interactive Terminal UI (auto-starts dev/socket/ext when paired with those commands)",
+		type: "boolean",
+		default: false,
+		global: true,
+	})
+	.command(
+		"ui",
+		"Open the interactive Terminal UI without auto-starting anything",
+		{},
+		() => {
+			// The dispatcher in bin/gx-devtools.js intercepts `ui` before yargs
+			// ever runs. Reaching this handler means the TUI bundle couldn't be
+			// launched (e.g. not built); bubble a helpful hint.
+			console.error(
+				'TUI is not available. Run "npm run build:tui" inside gx-devtools and try again.',
+			)
+			process.exit(1)
+		},
+	)
 	.command(
 		"init [name]",
-		"Initialize a new GxP project or update existing one",
+		"Initialize a new GxP project or update an existing one in the current directory",
 		{
 			name: {
 				describe: "Project name (for new projects)",
@@ -49,12 +79,13 @@ yargs
 			},
 			build: {
 				describe:
-					"AI build prompt - describe what to build for auto-scaffolding",
+					"Non-interactive AI scaffold: describe what to build and apply it directly",
 				type: "string",
 				alias: "b",
 			},
 			provider: {
-				describe: "AI provider for scaffolding (claude, codex, gemini)",
+				describe:
+					"AI provider for --build scaffolding (interactive mode picks from available CLIs)",
 				type: "string",
 				alias: "p",
 				choices: ["claude", "codex", "gemini"],
@@ -333,7 +364,31 @@ yargs
 		},
 		addDependencyCommand,
 	)
-	.demandCommand(1, "Please provide a valid command")
+	.command("$0", false, {}, () => {
+		cli.showHelp()
+	})
+	.example("gxdev init my-plugin", "Scaffold a new plugin called my-plugin")
+	.example(
+		"gxdev init",
+		"Add the toolkit to the current project (detects existing package.json)",
+	)
+	.example("gxdev dev", "Start Vite + Socket.IO in plain CLI mode")
+	.example("gxdev dev --ui", "Start the dev server inside the interactive TUI")
+	.example("gxdev ui", "Open the TUI without auto-starting anything")
+	.example("gxdev lint --all", "Lint configuration.json and app-manifest.json")
+	.example(
+		"gxdev extract-config",
+		"Sync app-manifest.json from gxp-string / gxp-src / store usage in src/",
+	)
+	.epilog(
+		[
+			"Docs:   https://docs.gxp.dev",
+			"AI/MCP: the gxp-api MCP server (bin: gxp-api-server) exposes 29 tools",
+			"        across API specs, config editing, docs search, and test helpers.",
+		].join("\n"),
+	)
 	.help("h")
 	.alias("h", "help")
-	.parse()
+	.strict(false)
+
+cli.parse()

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