@gxp-dev/tools 2.0.94 → 2.1.1

package/bin/lib/commands/dev.js

@@ -7,9 +7,17 @@
 
 const path = require("path")
 const fs = require("fs")
-const { spawn } = require("child_process")
+const childProcess = require("child_process")
 const shell = require("shelljs")
 const dotenv = require("dotenv")
+
+// Module-private spawn reference so tests can swap in a stub via
+// `setSpawnForTesting`. Production code paths still call the real
+// `child_process.spawn` because the default closes over it.
+let _spawn = childProcess.spawn
+function setSpawnForTesting(fn) {
+	_spawn = fn || childProcess.spawn
+}
 const {
 	findProjectRoot,
 	resolveGxPaths,
@@ -53,7 +61,7 @@ function createLogger(jsonMode) {
  * Returns the child process.
  */
 function spawnService(name, command, logger) {
-	const child = spawn(command, {
+	const child = _spawn(command, {
 		shell: true,
 		stdio: ["ignore", "pipe", "pipe"],
 		env: process.env,
@@ -289,8 +297,9 @@ function devCommand(argv) {
 		logger.info("🎭 Mock API will be enabled")
 	}
 
-	// Socket server starts by default unless --no-socket is passed
-	const noSocket = argv["no-socket"]
+	// Socket server starts by default unless --no-socket is passed. See
+	// shouldDisableSocket() for the yargs-negation quirk it papers over.
+	const noSocket = shouldDisableSocket(argv)
 	let serverJsPath = ""
 	if (!noSocket) {
 		// Check for local server.js first, then runtime directory
@@ -340,9 +349,10 @@ function devCommand(argv) {
 	if (!process.env.NODE_LOG_LEVEL) {
 		process.env.NODE_LOG_LEVEL = argv["node-log-level"] || "info"
 	}
-	if (!process.env.NODE_PORT) {
-		process.env.NODE_PORT = String(finalPort)
-	}
+	// NODE_PORT is the source of truth for the socket server (server.cjs reads
+	// process.env). Always set it to the resolved finalPort so that a CLI
+	// `--port` overrides anything that dotenv loaded from .env earlier.
+	process.env.NODE_PORT = String(finalPort)
 	if (!process.env.COMPONENT_PATH) {
 		process.env.COMPONENT_PATH = argv["component-path"] || "./src/Plugin.vue"
 	}
@@ -401,12 +411,15 @@ function devCommand(argv) {
 	// Normalize path separators to forward slashes for cross-platform shell compatibility
 	const normalizedViteConfigPath = viteConfigPath.replace(/\\/g, "/")
 
-	// Build the canonical service list (raw commands, no concurrently wrapping)
+	// Build the canonical service list (raw commands, no concurrently wrapping).
+	// Pass --port to vite directly: vite's loadEnv() only reads .env files —
+	// it does NOT inherit from process.env — so setting NODE_PORT above isn't
+	// enough on its own. The CLI flag wins over the config every time.
 	const services = []
 	services.push({
 		name: "VITE",
 		color: "cyan",
-		command: `npx vite dev --config "${normalizedViteConfigPath}"`,
+		command: `npx vite dev --config "${normalizedViteConfigPath}" --port ${finalPort}`,
 	})
 
 	if (serverJsPath) {
@@ -455,6 +468,23 @@ function devCommand(argv) {
 	shell.exec(command)
 }
 
+/**
+ * Pure helper exposed for unit testing the `--no-socket` flag-parsing fix.
+ * yargs interprets `--no-socket` from the CLI as `argv.socket = false`
+ * (boolean negation), NOT as `argv["no-socket"] = true`. We accept either
+ * form so the flag behaves the way the help text advertises.
+ */
+function shouldDisableSocket(argv) {
+	return argv["no-socket"] === true || argv.socket === false
+}
+
 module.exports = {
 	devCommand,
+	// Exposed for unit testing. These are pure-ish helpers that drive the
+	// NDJSON logger and child-process orchestration used by `gxdev dev`.
+	createLogger,
+	spawnService,
+	runServicesJson,
+	shouldDisableSocket,
+	setSpawnForTesting,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gxp-dev/tools",
-	"version": "2.0.94",
+	"version": "2.1.1",
 	"description": "Dev tools to create platform plugins",
 	"type": "commonjs",
 	"publishConfig": {
@@ -20,8 +20,10 @@
 	"scripts": {
 		"prepare": "git config core.hooksPath .githooks || true",
 		"test": "vitest run",
+		"test:run": "vitest run",
 		"test:watch": "vitest",
 		"test:coverage": "vitest run --coverage",
+		"test:e2e": "RUN_CLI_E2E=1 vitest run --config vitest.e2e.config.js",
 		"dev": "concurrently 'vite dev' 'nodemon config/server.js'",
 		"dev-app": "vite dev",
 		"ext:firefox": "web-ext run --source-dir browser-extensions/firefox",

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

@@ -685,7 +685,7 @@ async function handleAction() {
 
 onMounted(() => {
 	// Listen for real-time updates
-	store.listenSocket("primary", "DataUpdated", (eventData) => {
+	store.listen("primary", "DataUpdated", (eventData) => {
 		data.value = eventData
 	})
 })
@@ -743,11 +743,18 @@ npm run dev          # HTTPS with Socket.IO
 npm run dev-http     # HTTP only
 
 # Test socket events
-gxdev socket list              # List available events
-gxdev socket send --event Name # Send test broadcast
+gxdev socket list                           # List available events
+gxdev socket send --event Name              # Send test broadcast
+gxdev socket send --event Name --identifier id  # Send to a specific channel
+
+# Dependencies
+gxdev add-dependency                        # Interactive wizard: search endpoints and add dependency to app-manifest.json
+
+# UIKit components
+gxdev storybook                             # Browse components at http://localhost:6006
 
 # Lint
-gxdev lint --all               # Validate configuration.json + app-manifest.json
+gxdev lint --all                            # Validate configuration.json + app-manifest.json
 
 # Build for production
 gxdev build          # Creates dist/ with .gxpapp package

package/template/AGENTS.md

@@ -37,7 +37,7 @@ Use the `gxp-api` MCP server to ground the implementation in the real platform
 - **Inspect a specific endpoint** — `api_get_operation_parameters`, `get_endpoint_details`.
 - **Find endpoints by payload shape** — `api_find_endpoints_by_schema` (search by request/response field names).
 - **Find WebSocket events** — `api_find_events_for_operation` (given an operationId, returns events via `x-triggered-by`), `api_list_events`, `search_websocket_events`, `get_asyncapi_spec`. Run `api_find_events_for_operation` for every operationId you plan to call so you subscribe instead of polling.
-- **Generate dependency JSON** — `api_generate_dependency` produces the canonical entry for `app-manifest.json` → `dependencies`.
+- **Generate dependency JSON** — `api_generate_dependency` produces the canonical entry for `app-manifest.json` → `dependencies`. Alternatively, `gxdev add-dependency` runs an interactive CLI wizard that searches endpoints and writes the entry directly to `app-manifest.json`.
 - **Read the docs** — `docs_list_pages`, `docs_search`, `docs_get_page` (full-text search across docs.gxp.dev).
 
 Output of this step: a short list of the operationIds, WebSocket events, and dependencies the plugin will use.
@@ -89,7 +89,7 @@ As soon as you've added a new `store.callApi`, `store.listen`, `gxp-string`, or
 Before declaring done, exercise the plugin against real event shapes:
 
 - List available events — `gxdev socket list`.
-- Send one — `gxdev socket send --event <EventName>` (edit or add payloads under `socket-events/`).
+- Send one — `gxdev socket send --event <EventName>` (edit or add payloads under `socket-events/`). Use `--identifier <id>` to override which channel the event fires on.
 - Hit endpoints against the local mock API via the `test_api_route` MCP tool.
 - Scaffold unit tests with `test_scaffold_component_test` for any non-trivial component.
 
@@ -452,7 +452,11 @@ Strings, assets, dependencies, colors → `additionalTabs`. Quiz/survey question
 
 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.
 
-Available: GxButton, GxCard, GxInput, GxModal, GxSpinner, GxAlert, GxBadge, GxAvatar, GxProgress, GxTabs, GxAccordion
+## Component Kit
+
+Use `@gxp-dev/uikit` for all UI components. Run `gxdev storybook` to browse available components and their stories at `http://localhost:6006`. When storybook is running, the `gxp-uikit-storybook` MCP server (registered in `.mcp.json`) provides tools to inspect stories, documentation, and run story tests directly from your AI assistant.
+
+Key components: `GxButton`, `GxCard`, `GxInput`, `GxModal`, `GxSpinner`, `GxAlert`, `GxBadge`, `GxAvatar`, `GxProgress`, `GxTabs`, `GxAccordion`
 
 ## Configuration Files
 
@@ -471,9 +475,10 @@ gxdev lint --json    # machine-readable output
 
 ## Testing
 
-- Socket events: `gxdev socket send --event EventName`
+- Socket events: `gxdev socket send --event EventName` (add `--identifier <id>` to target a specific channel)
 - API calls against local mock: `test_api_route` MCP tool
 - Component tests: `test_scaffold_component_test` MCP tool
+- UIKit components: `gxdev storybook` — browse components at `http://localhost:6006`
 - Dev Tools: Press Ctrl+Shift+D
 - Console: `window.gxDevTools.store()` to inspect store
 
@@ -482,6 +487,7 @@ gxdev lint --json    # machine-readable output
 Set `VITE_API_ENV` in `.env`:
 
 - `mock` - Local mock server (default)
+- `local` - https://dashboard.eventfinity.test
 - `develop` - https://api.zenith-develop.env.eventfinity.app
 - `staging` - https://api.efz-staging.env.eventfinity.app
 - `production` - https://api.gramercy.cloud

package/template/GEMINI.md

@@ -31,7 +31,7 @@ Ground the implementation in real platform endpoints and events. Do not invent A
 - Endpoints — `api_list_tags`, `api_list_operation_ids`, `search_api_endpoints`, `api_get_operation_parameters`, `get_endpoint_details`.
 - Find by payload shape — `api_find_endpoints_by_schema`.
 - WebSocket events — `api_find_events_for_operation` (maps operationId → events via `x-triggered-by`), `api_list_events`, `search_websocket_events`, `get_asyncapi_spec`. Run for every planned operationId so you subscribe instead of polling.
-- Canonical dependency JSON — `api_generate_dependency`.
+- Canonical dependency JSON — `api_generate_dependency`. Or run `gxdev add-dependency` for an interactive CLI wizard that writes the entry directly to `app-manifest.json`.
 - Documentation — `docs_list_pages`, `docs_search`, `docs_get_page`.
 
 ### 3. Plan with the client
@@ -67,7 +67,7 @@ Whenever you add or change a `store.callApi`, `store.listen`, `gxp-string`, or `
 ### 6. Test broadcasts
 
 - `gxdev socket list` — see available events.
-- `gxdev socket send --event <EventName>` — fire a test broadcast.
+- `gxdev socket send --event <EventName>` — fire a test broadcast. Add `--identifier <id>` to target a specific channel.
 - `test_api_route` MCP tool — hit endpoints against the local mock.
 - `test_scaffold_component_test` MCP tool — generate Vitest files.
 
@@ -280,7 +280,19 @@ Tools: `config_list_card_types`, `config_list_field_types`, `config_get_field_sc
 
 ## Component Kit
 
-Use `@gxp-dev/uikit` for UI
+Use `@gxp-dev/uikit` for all UI components. Run `gxdev storybook` to browse available components at `http://localhost:6006`. When storybook is running, the `gxp-uikit-storybook` MCP server (registered in `.mcp.json`) provides tools to inspect stories and documentation.
+
+Key components: `GxButton`, `GxCard`, `GxInput`, `GxModal`, `GxSpinner`, `GxAlert`, `GxBadge`, `GxAvatar`, `GxProgress`, `GxTabs`, `GxAccordion`
+
+## API Environments
+
+Set `VITE_API_ENV` in `.env`:
+
+- `mock` - Local mock server (default)
+- `local` - https://dashboard.eventfinity.test
+- `develop` - https://api.zenith-develop.env.eventfinity.app
+- `staging` - https://api.efz-staging.env.eventfinity.app
+- `production` - https://api.gramercy.cloud
 
 ## API Specs