@gxp-dev/tools 2.0.73 → 2.0.75

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

@@ -506,14 +506,19 @@ async function runInteractiveConfig(projectPath, initialName, isLocal = false) {
 
 	// 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.
+	//
+	// Print the project-ready summary BEFORE we hand stdin/stdout to the agent
+	// so the user sees "setup complete, here's how to start the dev server"
+	// up front. Once the agent owns the terminal the init script is done — it
+	// won't print anything else on the way out.
 	if (selectedProvider) {
+		printFinalInstructions(projectPath, appName, sslSetup, isLocal)
 		await launchInteractiveAISession(
 			projectPath,
 			appName,
 			description,
 			selectedProvider,
 		)
-		printFinalInstructions(projectPath, appName, sslSetup, isLocal)
 		return null
 	}
 

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

@@ -1069,10 +1069,13 @@ function launchInteractiveAISession(
 		console.log("   implement. Exit the agent when you're done.")
 		console.log("")
 
+		// Do NOT pass shell: true here. The initial prompt contains backticks,
+		// parentheses, and quotes; going through /bin/sh -c would require
+		// shell-escaping every special character. Without shell: true, spawn
+		// execs the binary directly and the argv is delivered as-is.
 		const child = spawn(command, args, {
 			cwd: projectPath,
 			stdio: "inherit",
-			shell: true,
 		})
 
 		child.on("close", (code) => {

package/package.json

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