@gxp-dev/tools 2.0.5

package/REFACTOR_PLAN.md

@@ -0,0 +1,194 @@
+# GxP Toolkit Refactoring Plan
+
+## Status: COMPLETED
+
+All major refactoring phases have been completed. This document is kept for reference.
+
+---
+
+## Phase 1: CLI Refactoring ✅ COMPLETED
+
+### Goal
+Break `bin/gx-devtools.js` (2407 lines) into focused modules while maintaining backward compatibility.
+
+### Final Structure
+```
+bin/
+├── gx-devtools.js          # Entry point (~25 lines) - delegates to lib/cli.js
+└── lib/
+    ├── cli.js             # Yargs command definitions
+    ├── constants.js       # Dependencies, scripts, ports
+    ├── commands/
+    │   ├── init.js        # gxdev init
+    │   ├── dev.js         # gxdev dev
+    │   ├── build.js       # gxdev build
+    │   ├── publish.js     # gxdev publish
+    │   ├── ssl.js         # gxdev setup-ssl
+    │   ├── datastore.js   # gxdev datastore <action>
+    │   ├── socket.js      # gxdev socket <action>
+    │   ├── assets.js      # gxdev assets <action>
+    │   ├── extensions.js  # gxdev ext:*
+    │   └── index.js       # Re-exports all commands
+    └── utils/
+        ├── paths.js       # Path resolution (findProjectRoot, resolveGxPaths, etc.)
+        ├── ssl.js         # SSL certificate management
+        ├── files.js       # File operations (safeCopyFile, etc.)
+        ├── prompts.js     # User prompts (promptUser)
+        └── index.js       # Re-exports all utilities
+```
+
+### Completed Tasks
+- [x] Create `bin/lib/` directory structure
+- [x] Extract path resolution utilities to `utils/paths.js`
+- [x] Extract SSL management to `utils/ssl.js`
+- [x] Extract file utilities to `utils/files.js`
+- [x] Extract prompts to `utils/prompts.js`
+- [x] Extract dependency constants to `constants.js`
+- [x] Create individual command modules
+- [x] Update main entry point to use modular CLI
+- [x] Test all commands work identically
+- [x] Renamed CLI command from `gxto` to `gxdev`
+
+---
+
+## Phase 2: Folder Structure Cleanup ✅ COMPLETED
+
+### Goal
+Clean up the template system and establish clear boundaries.
+
+### Final Structure
+```
+gx-devtools/
+├── bin/                    # CLI (refactored)
+│   └── lib/                # Modular CLI components
+├── template/               # Files copied to new projects during init
+│   ├── src/
+│   │   ├── Plugin.vue      # User's entry point (editable)
+│   │   ├── DemoPage.vue    # Example component (editable)
+│   │   └── stores/         # Store templates
+│   ├── theme-layouts/      # Layout templates (editable)
+│   ├── dev-assets/         # Placeholder images
+│   ├── main.js             # Dev entry point (imports from @gx-runtime)
+│   ├── index.html
+│   ├── vite.config.js      # Project vite config with aliases
+│   ├── app-manifest.json
+│   ├── env.example
+│   ├── gitignore
+│   └── README.md
+├── runtime/                # Files used from node_modules (NOT copied)
+│   ├── PortalContainer.vue # Platform emulator (immutable)
+│   ├── server.js           # Socket.IO server
+│   ├── dev-tools/          # In-browser dev tools
+│   │   ├── DevToolsModal.vue
+│   │   ├── StoreInspector.vue
+│   │   ├── LayoutSwitcher.vue
+│   │   ├── SocketSimulator.vue
+│   │   └── MockDataEditor.vue
+│   └── stores/
+│       └── gxpPortalConfigStore.js
+├── socket-events/          # Event templates (single source of truth)
+├── browser-extensions/     # Chrome/Firefox extensions
+└── scripts/                # Build/launch scripts
+```
+
+### Completed Tasks
+- [x] Create `/runtime/` directory
+- [x] Move PortalContainer.vue to /runtime/
+- [x] Move server.js to /runtime/
+- [x] Move gxpPortalConfigStore.js to /runtime/stores/
+- [x] Consolidate socket-events to single location
+- [x] Update CLI path resolution
+- [x] Update template/main.js to import from @gx-runtime
+- [x] Update template/vite.config.js with aliases (@, @layouts, @gx-runtime)
+- [x] Test `gxdev init` creates correct project structure
+
+---
+
+## Phase 3: PortalContainer Immutability ✅ COMPLETED
+
+### Goal
+Make PortalContainer.vue truly hidden from client projects while still functional for development.
+
+### Implementation
+- PortalContainer.vue is in `/runtime/` (NOT copied during init)
+- Client's main.js imports via Vite alias: `import App from "@gx-runtime/PortalContainer.vue"`
+- Vite config defines `@gx-runtime` alias pointing to toolkit's runtime directory
+
+### Completed Tasks
+- [x] Move PortalContainer.vue to /runtime/
+- [x] Update template/main.js import path
+- [x] Update template/vite.config.js with @gx-runtime alias
+- [x] Test development server loads PortalContainer from node_modules
+- [x] Document this architecture in CLAUDE.md
+
+---
+
+## Phase 4: Dev Tools Configuration Modal ✅ COMPLETED
+
+### Goal
+Create an in-browser development tools modal.
+
+### Features Implemented
+1. **Store Inspector** - View/edit pluginVars, stringsList, assetList, triggerState, dependencyList
+2. **Layout Switcher** - Toggle between System/Private/Public layouts
+3. **Socket Simulator** - Send test socket events with JSON editor
+4. **Mock Data Editor** - Edit theme colors, navigation items, user session, permissions
+
+### Triggers
+- **Keyboard shortcut:** `Ctrl+Shift+D` (or `Cmd+Shift+D` on Mac)
+- **Floating button:** Gear icon in bottom-right corner
+- **Console API:** `window.gxDevTools.open()` / `.close()` / `.toggle()`
+
+### Files Created
+```
+runtime/dev-tools/
+├── DevToolsModal.vue      # Main modal with tabs
+├── StoreInspector.vue     # Store state viewer/editor
+├── LayoutSwitcher.vue     # Layout toggle
+├── SocketSimulator.vue    # Socket event sender
+├── MockDataEditor.vue     # Theme/nav/permissions editor
+└── index.js               # Exports
+```
+
+### Completed Tasks
+- [x] Create DevToolsModal.vue with tabbed interface
+- [x] Implement StoreInspector with collapsible sections
+- [x] Implement LayoutSwitcher
+- [x] Implement SocketSimulator with event log
+- [x] Implement MockDataEditor
+- [x] Add keyboard shortcut handling
+- [x] Add console command API
+- [x] Add floating trigger button
+- [x] Integrate into PortalContainer.vue
+- [x] Document in CLAUDE.md
+
+---
+
+## Phase 5: Cleanup & Polish ✅ COMPLETED
+
+### Completed Tasks
+- [x] Update CLAUDE.md with new structure and dev tools docs
+- [x] Update template/README.md with gxdev commands
+- [x] Rename CLI from `gxto` to `gxdev`
+- [x] Update all code references and documentation
+- [x] Add .gitignore template file
+- [x] Fix init command paths for new folder structure
+
+---
+
+## Summary of Changes
+
+### CLI Command Rename
+- Old: `gxto`
+- New: `gxdev`
+
+### Key Architecture Changes
+1. **Monolithic CLI** → **Modular structure** in `bin/lib/`
+2. **Mixed config/** → **Separate template/ and runtime/ directories**
+3. **Exposed PortalContainer** → **Hidden in runtime/, accessed via @gx-runtime alias**
+4. **No dev tools** → **Full dev tools modal with 4 panels**
+
+### Vite Aliases (in projects)
+- `@` → Project's `src/` directory
+- `@layouts` → Project's `theme-layouts/` directory
+- `@gx-runtime` → Toolkit's `runtime/` directory (from node_modules)

package/bin/gx-devtools.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * GxToolkit CLI
+ *
+ * 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.
+ *
+ * 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
+ */
+
+// Commands that should use the traditional CLI (one-shot commands)
+const ONE_SHOT_COMMANDS = ['init', 'build', 'publish', 'setup-ssl', 'ext:build', '--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);
+
+// 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');
+
+  if (fs.existsSync(tuiPath)) {
+    // Use dynamic import() for ESM modules (ink v5 is ESM-only)
+    (async () => {
+      try {
+        const { startTUI } = await import(tuiPath);
+
+        // Determine auto-start commands
+        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');
+        }
+
+        startTUI({ autoStart, args: tuiArgs });
+      } catch (err) {
+        // TUI dependencies not available, fall back to traditional CLI
+        console.error('TUI error:', err.message);
+        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.');
+    require("./lib/cli");
+  }
+} else {
+  // One-shot command, use traditional CLI
+  require("./lib/cli");
+}

package/bin/lib/cli.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+/**
+ * GxToolkit CLI Entry Point
+ *
+ * This is the main entry point for the gxdev CLI tool.
+ * It sets up yargs commands and delegates to the appropriate command modules.
+ */
+
+const yargs = require("yargs");
+const { loadGlobalConfig } = require("./utils");
+const {
+	initCommand,
+	devCommand,
+	buildCommand,
+	publishCommand,
+	setupSSLCommand,
+	datastoreCommand,
+	socketCommand,
+	assetsCommand,
+	extensionFirefoxCommand,
+	extensionChromeCommand,
+	extensionBuildCommand,
+	extensionInstallCommand,
+} = require("./commands");
+
+// Load global configuration
+const globalConfig = loadGlobalConfig();
+
+// Set up yargs CLI
+yargs
+	.usage("$0 <command>")
+	.config(globalConfig)
+	.command(
+		"init [name]",
+		"Initialize a new GxP project or update existing one",
+		{
+			name: {
+				describe: "Project name (for new projects)",
+				type: "string",
+			},
+		},
+		initCommand
+	)
+	.command(
+		"setup-ssl",
+		"Setup SSL certificates for HTTPS development",
+		{},
+		setupSSLCommand
+	)
+	.command(
+		"dev",
+		"Start development server",
+		{
+			port: {
+				describe: "Development server port",
+				type: "number",
+			},
+			"node-log-level": {
+				describe: "Node log level",
+				type: "string",
+				default: "info",
+			},
+			"component-path": {
+				describe: "Path to main component",
+				type: "string",
+				default: "./src/Plugin.vue",
+			},
+			"no-https": {
+				describe: "Disable HTTPS and use HTTP instead",
+				type: "boolean",
+				default: false,
+			},
+			"with-socket": {
+				describe: "Also start Socket.IO server with nodemon",
+				type: "boolean",
+				default: false,
+				alias: "s",
+			},
+			firefox: {
+				describe: "Launch Firefox with browser extension",
+				type: "boolean",
+				default: false,
+			},
+			chrome: {
+				describe: "Launch Chrome with browser extension",
+				type: "boolean",
+				default: false,
+			},
+			"with-mock": {
+				describe: "Enable Mock API server (requires --with-socket)",
+				type: "boolean",
+				default: false,
+				alias: "m",
+			},
+		},
+		devCommand
+	)
+	.command(
+		"build",
+		"Build plugin for production",
+		{
+			"node-log-level": {
+				describe: "Node log level",
+				type: "string",
+				default: "error",
+			},
+			"component-path": {
+				describe: "Path to main component",
+				type: "string",
+				default: "./src/Plugin.vue",
+			},
+		},
+		buildCommand
+	)
+	.command(
+		"publish [file]",
+		"Publish package files to local project",
+		{
+			file: {
+				describe: "File to publish (server.js, gxpPortalConfigStore.js)",
+				type: "string",
+			},
+		},
+		publishCommand
+	)
+	.command(
+		"datastore <action>",
+		"Manage GxP datastore",
+		{
+			action: {
+				describe: "Action to perform",
+				choices: ["list", "add", "scan-strings", "config", "init"],
+			},
+			type: {
+				describe: "Variable type (for add command)",
+				choices: ["string", "setting", "asset"],
+			},
+			key: {
+				describe: "Variable key/name (for add command)",
+				type: "string",
+			},
+			value: {
+				describe: "Variable value (for add command)",
+				type: "string",
+			},
+			component: {
+				describe: "Component path (for scan-strings command)",
+				type: "string",
+			},
+			config: {
+				describe: "Configuration name (for config command)",
+				type: "string",
+			},
+		},
+		datastoreCommand
+	)
+	.command(
+		"ext:firefox",
+		"Launch Firefox with browser extension",
+		{},
+		extensionFirefoxCommand
+	)
+	.command(
+		"ext:chrome",
+		"Launch Chrome with browser extension",
+		{},
+		extensionChromeCommand
+	)
+	.command(
+		"ext:build",
+		"Build browser extensions for distribution",
+		{},
+		extensionBuildCommand
+	)
+	.command(
+		"ext:install <browser>",
+		"Install extension permanently in local browser",
+		{
+			browser: {
+				describe: "Browser to install extension in",
+				choices: ["chrome", "firefox"],
+				type: "string",
+			},
+		},
+		extensionInstallCommand
+	)
+	.command(
+		"socket <action>",
+		"Simulate socket events",
+		{
+			action: {
+				describe: "Action to perform",
+				choices: ["list", "send"],
+			},
+			event: {
+				describe: "Event name to send (for send action)",
+				type: "string",
+			},
+			identifier: {
+				describe: "Override identifier/channel (for send action)",
+				type: "string",
+			},
+		},
+		socketCommand
+	)
+	.command(
+		"assets <action>",
+		"Manage development assets and placeholders",
+		{
+			action: {
+				describe: "Action to perform",
+				choices: ["list", "generate", "init"],
+			},
+			size: {
+				describe: "Image size (for generate action)",
+				type: "string",
+				default: "400x300",
+			},
+			name: {
+				describe: "Asset name (for generate action)",
+				type: "string",
+				default: "placeholder",
+			},
+			color: {
+				describe: "Background color (for generate action)",
+				type: "string",
+			},
+			text: {
+				describe: "Text to display (for generate action)",
+				type: "string",
+			},
+			format: {
+				describe: "Image format (for generate action)",
+				type: "string",
+				choices: ["png", "jpg", "jpeg", "gif"],
+				default: "png",
+			},
+			count: {
+				describe:
+					"Number of assets to generate with different colors/styles (for generate action)",
+				type: "number",
+				default: 1,
+			},
+		},
+		assetsCommand
+	)
+	.demandCommand(1, "Please provide a valid command")
+	.help("h")
+	.alias("h", "help")
+	.parse();