@gxp-dev/tools 2.0.5

package/docs/getting-started.md

@@ -0,0 +1,180 @@
+---
+sidebar_position: 2
+title: Getting Started
+description: Install the GxP Toolkit and create your first plugin project
+---
+
+# Getting Started
+
+This guide walks you through installing the GxP Toolkit and creating your first plugin project.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **Node.js 18+** - [Download Node.js](https://nodejs.org/)
+- **npm 8+** - Comes with Node.js
+- **Code editor** - VS Code recommended
+
+## Installation
+
+### Option 1: Global Installation (Recommended)
+
+Install the toolkit globally to use the `gxdev` command anywhere:
+
+```bash
+npm install -g @gramercytech/gx-devtools
+```
+
+### Option 2: Project-Level Installation
+
+Or install as a dev dependency in an existing project:
+
+```bash
+npm install --save-dev @gramercytech/gx-devtools
+```
+
+## Create a New Plugin
+
+### 1. Initialize Your Project
+
+Create a new plugin project using the CLI:
+
+```bash
+# Create a new directory and initialize
+mkdir my-plugin
+cd my-plugin
+gxdev init my-plugin
+```
+
+This creates a complete project structure with:
+
+- `src/Plugin.vue` - Your main plugin component
+- `app-manifest.json` - Plugin configuration
+- `theme-layouts/` - Layout components for different contexts
+- `dev-assets/` - Development placeholder assets
+
+### 2. Install Dependencies
+
+```bash
+npm install
+```
+
+### 3. Start Development Server
+
+Start the development server with hot reload:
+
+```bash
+# With HTTPS (recommended)
+npm run dev
+
+# Without HTTPS (simpler setup)
+npm run dev-http
+```
+
+Your plugin is now running at `https://localhost:3060` (or `http://localhost:3060`).
+
+## Project Structure
+
+After initialization, your project looks like this:
+
+```
+my-plugin/
+├── src/
+│   ├── Plugin.vue          # Main plugin entry point
+│   ├── DemoPage.vue        # Example component
+│   └── stores/
+│       └── index.js        # Store setup
+├── theme-layouts/
+│   ├── PublicLayout.vue    # Public-facing layout
+│   ├── PrivateLayout.vue   # Authenticated layout
+│   └── SystemLayout.vue    # System/admin layout
+├── dev-assets/
+│   └── images/             # Development placeholder images
+├── app-manifest.json       # Plugin configuration
+├── vite.config.js          # Vite configuration
+├── main.js                 # Development entry point
+├── index.html              # Development HTML template
+└── .env                    # Environment variables
+```
+
+## Your First Edit
+
+Open `src/Plugin.vue` and make a change:
+
+```vue
+<template>
+  <div class="my-plugin">
+    <h1 gxp-string="welcome_title">Welcome to My Plugin!</h1>
+    <p>Edit this file to get started.</p>
+  </div>
+</template>
+
+<script setup>
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+
+const store = useGxpStore();
+</script>
+```
+
+The page automatically refreshes with your changes.
+
+## SSL Setup (Optional)
+
+For HTTPS development (required for some platform features):
+
+```bash
+npm run setup-ssl
+```
+
+This uses [mkcert](https://github.com/FiloSottile/mkcert) to generate trusted local certificates.
+
+## Using the Interactive TUI
+
+Run `gxdev` without arguments to launch the interactive Terminal UI:
+
+```bash
+gxdev
+```
+
+The TUI provides:
+
+- **Service management** - Start/stop Vite, Socket.IO, extensions
+- **Log viewing** - Real-time logs from all services
+- **Slash commands** - Quick actions like `/dev`, `/socket`, `/ext chrome`
+
+### TUI Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+1/2/3...` | Switch service tabs |
+| `Ctrl+L` | Clear current log |
+| `Ctrl+C` | Exit application |
+| `Up/Down` | Scroll log panel |
+
+## Next Steps
+
+- [Configure your app manifest](./app-manifest) - Set up strings, settings, and assets
+- [Learn the GxP Store](./gxp-store) - State management and platform integration
+- [Use Dev Tools](./dev-tools) - Debug and inspect your plugin
+- [Build for platform](./building-for-platform) - Prepare for production deployment
+
+## Common Commands Reference
+
+```bash
+# Development
+gxdev dev                    # Start with TUI + Vite
+gxdev dev --no-https         # Start without SSL
+gxdev dev --with-socket      # Include Socket.IO server
+gxdev dev --chrome           # Launch with Chrome extension
+gxdev dev --firefox          # Launch with Firefox extension
+
+# Building
+gxdev build                  # Build for production
+
+# Utilities
+gxdev datastore list         # List store variables
+gxdev datastore scan-strings # Find hardcoded strings
+gxdev socket list            # List socket events
+gxdev assets generate        # Generate placeholder images
+```

package/docs/gxp-store.md

@@ -0,0 +1,305 @@
+---
+sidebar_position: 4
+title: GxP Store
+description: State management with Pinia and platform integration
+---
+
+# GxP Store
+
+The GxP Store (`gxpPortalConfigStore`) is a Pinia store that provides reactive state management and platform integration for your plugin.
+
+## Importing the Store
+
+```javascript
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+
+// In your component setup
+const store = useGxpStore();
+```
+
+## Store Sections
+
+The store contains several reactive sections populated from your `app-manifest.json` and the platform:
+
+| Section | Description | Source |
+|---------|-------------|--------|
+| `pluginVars` | Plugin settings/configuration | `settings` in manifest |
+| `stringsList` | Translatable strings | `strings.default` in manifest |
+| `assetList` | Asset URLs | `assets` in manifest |
+| `triggerState` | Dynamic runtime state | `triggerState` in manifest |
+| `dependencyList` | External dependencies | Platform-injected |
+| `permissionFlags` | Granted permissions | Platform-injected |
+| `theme` | Platform theme colors | Platform-injected |
+| `router` | Navigation methods | Platform-injected |
+
+## Getter Methods
+
+Use these methods to safely access store values with fallbacks:
+
+### `getString(key, defaultValue)`
+
+Get a string from `stringsList`:
+
+```javascript
+const title = store.getString('welcome_title', 'Welcome');
+const button = store.getString('btn_submit', 'Submit');
+```
+
+### `getSetting(key, defaultValue)`
+
+Get a setting from `pluginVars`:
+
+```javascript
+const color = store.getSetting('primary_color', '#000000');
+const timeout = store.getSetting('idle_timeout', 30);
+const enabled = store.getSetting('feature_enabled', false);
+```
+
+### `getAsset(key, defaultValue)`
+
+Get an asset URL from `assetList`:
+
+```javascript
+const logo = store.getAsset('logo', '/fallback-logo.png');
+const hero = store.getAsset('hero_image', '/placeholder.jpg');
+```
+
+### `getState(key, defaultValue)`
+
+Get a value from `triggerState`:
+
+```javascript
+const step = store.getState('current_step', 1);
+const isActive = store.getState('is_active', false);
+```
+
+### `hasPermission(permission)`
+
+Check if a permission is granted:
+
+```javascript
+if (store.hasPermission('camera')) {
+  // Camera access is available
+}
+
+if (store.hasPermission('bluetooth')) {
+  // Bluetooth access is available
+}
+```
+
+## Update Methods
+
+### `updateString(key, value)`
+
+Update a string value:
+
+```javascript
+store.updateString('dynamic_message', 'Processing your request...');
+```
+
+### `updateSetting(key, value)`
+
+Update a setting value:
+
+```javascript
+store.updateSetting('current_mode', 'advanced');
+```
+
+### `updateAsset(key, url)`
+
+Update an asset URL:
+
+```javascript
+store.updateAsset('user_avatar', 'https://example.com/avatar.jpg');
+```
+
+### `updateState(key, value)`
+
+Update trigger state:
+
+```javascript
+store.updateState('current_step', 2);
+store.updateState('is_loading', true);
+store.updateState('selected_item', { id: 123, name: 'Item' });
+```
+
+### `addDevAsset(key, filename)`
+
+Add a development asset with the dev server URL prefix:
+
+```javascript
+// Automatically prefixes with dev server URL
+store.addDevAsset('temp_image', 'screenshot.png');
+// Result: https://localhost:3060/dev-assets/images/screenshot.png
+```
+
+## API Client
+
+The store includes an Axios-based API client for making HTTP requests:
+
+### `apiGet(endpoint, params)`
+
+```javascript
+const response = await store.apiGet('/events/123');
+const events = await store.apiGet('/events', { status: 'active' });
+```
+
+### `apiPost(endpoint, data)`
+
+```javascript
+const result = await store.apiPost('/checkin', {
+  attendee_id: 456,
+  timestamp: new Date().toISOString()
+});
+```
+
+### `apiPut(endpoint, data)`
+
+```javascript
+await store.apiPut('/attendees/456', {
+  checked_in: true
+});
+```
+
+### `apiDelete(endpoint)`
+
+```javascript
+await store.apiDelete('/sessions/789');
+```
+
+## Socket.IO Integration
+
+The store provides methods for real-time communication via Socket.IO:
+
+### `emitSocket(channel, event, data)`
+
+Send a socket event:
+
+```javascript
+store.emitSocket('primary', 'checkin-complete', {
+  attendee_id: 123,
+  badge_printed: true
+});
+```
+
+### `listenSocket(channel, event, callback)`
+
+Listen for socket events:
+
+```javascript
+store.listenSocket('primary', 'session-updated', (data) => {
+  console.log('Session updated:', data);
+  store.updateState('current_session', data);
+});
+```
+
+### `useSocketListener(dependencyId, event, callback)`
+
+Set up a socket listener for a specific dependency:
+
+```javascript
+store.useSocketListener('badge-printer', 'print-complete', (result) => {
+  if (result.success) {
+    store.updateState('badge_printing', false);
+  }
+});
+```
+
+## Reactive Usage in Templates
+
+The store is fully reactive. Use it directly in your templates:
+
+```vue
+<template>
+  <div :style="{ backgroundColor: store.getSetting('bg_color', '#fff') }">
+    <h1>{{ store.getString('title', 'Default Title') }}</h1>
+
+    <p v-if="store.triggerState.is_loading">Loading...</p>
+
+    <div v-for="item in store.triggerState.items" :key="item.id">
+      {{ item.name }}
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+
+const store = useGxpStore();
+</script>
+```
+
+## Watching Store Changes
+
+Use Vue's `watch` to react to store changes:
+
+```javascript
+import { watch } from 'vue';
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+
+const store = useGxpStore();
+
+// Watch a specific state value
+watch(
+  () => store.triggerState.current_step,
+  (newStep, oldStep) => {
+    console.log(`Step changed from ${oldStep} to ${newStep}`);
+  }
+);
+
+// Watch multiple values
+watch(
+  () => [store.triggerState.is_active, store.pluginVars.mode],
+  ([isActive, mode]) => {
+    if (isActive && mode === 'kiosk') {
+      startKioskMode();
+    }
+  }
+);
+```
+
+## Computed Properties
+
+Create computed properties based on store values:
+
+```javascript
+import { computed } from 'vue';
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+
+const store = useGxpStore();
+
+const isReady = computed(() =>
+  !store.triggerState.is_loading &&
+  store.triggerState.data !== null
+);
+
+const formattedCount = computed(() =>
+  `${store.triggerState.checked_in_count} of ${store.pluginVars.total_expected}`
+);
+```
+
+## Theme Integration
+
+Access platform theme values:
+
+```javascript
+const store = useGxpStore();
+
+// Theme colors
+const primaryColor = store.theme?.primary || '#1976D2';
+const backgroundColor = store.theme?.background || '#ffffff';
+
+// Use in styles
+const buttonStyle = computed(() => ({
+  backgroundColor: store.theme?.primary,
+  color: store.theme?.onPrimary
+}));
+```
+
+## Best Practices
+
+1. **Use getters with defaults** - Always provide fallback values
+2. **Keep state updates atomic** - Update one value at a time when possible
+3. **Use computed for derived state** - Don't duplicate logic
+4. **Clean up listeners** - Remove socket listeners when components unmount
+5. **Avoid deep nesting** - Keep `triggerState` relatively flat for reactivity

package/docs/index.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 1
+title: GxP Toolkit Overview
+description: Introduction to the GxP Dev Toolkit for building platform plugins
+slug: /gx-devtools
+---
+
+# GxP Dev Toolkit
+
+The GxP Dev Toolkit (`@gramercytech/gx-devtools`) is an npm package for creating platform plugins for the GxP kiosk platform.
+
+## What You Can Build
+
+With the GxP Toolkit, you can create custom plugins that run on GxP kiosks, including:
+
+- **Interactive displays** - Check-in kiosks, registration flows, badge printing
+- **Information screens** - Schedules, maps, directories
+- **Engagement features** - Surveys, gamification, social walls
+- **Custom integrations** - Connect to external APIs and services
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **CLI Tool** | `gxdev` command for scaffolding and development |
+| **Interactive TUI** | Terminal UI for managing dev services |
+| **Hot Reload** | Vite-based dev server with instant updates |
+| **Socket.IO** | Real-time event simulation |
+| **Browser Extensions** | Test plugins in production environments |
+| **Vue 3 + Pinia** | Modern reactive framework with state management |
+
+## Quick Links
+
+- [Getting Started](./getting-started) - Install and create your first plugin
+- [App Manifest](./app-manifest) - Configure your plugin settings, strings, and assets
+- [GxP Store](./gxp-store) - State management and platform integration
+- [Dev Tools](./dev-tools) - In-browser debugging and inspection
+- [Building for Platform](./building-for-platform) - Prepare your plugin for production
+
+## Requirements
+
+- Node.js 18 or higher
+- npm 8 or higher
+- Modern browser (Chrome, Firefox, Safari, Edge)

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@gxp-dev/tools",
+  "version": "2.0.5",
+  "description": "Dev tools to create platform plugins",
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "concurrently 'vite dev' 'nodemon config/server.js'",
+    "dev-app": "vite dev",
+    "ext:firefox": "web-ext run --source-dir browser-extensions/firefox",
+    "ext:firefox-build": "web-ext build --source-dir browser-extensions/firefox --artifacts-dir dist/firefox",
+    "ext:chrome": "node scripts/launch-chrome.js",
+    "ext:chrome-pack": "node scripts/pack-chrome.js",
+    "ext:install": "npm run ext:firefox & npm run ext:chrome",
+    "ext:build": "npm run ext:firefox-build && npm run ext:chrome-pack",
+    "build:tui": "tsc -p tsconfig.tui.json && echo '{\"type\":\"module\"}' > dist/tui/package.json",
+    "dev:tui": "tsx watch bin/lib/tui/index.tsx"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/GramercyTech/gx-devtools.git"
+  },
+  "bin": {
+    "gxdev": "bin/gx-devtools.js"
+  },
+  "keywords": [
+    "tunnel",
+    "gtcp",
+    "eventfinity",
+    "gxp"
+  ],
+  "author": "Peek",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/GramercyTech/gx-devtools/issues"
+  },
+  "homepage": "https://github.com/GramercyTech/gx-devtools#readme",
+  "dependencies": {
+    "@faker-js/faker": "^9.9.0",
+    "@fal-works/esbuild-plugin-global-externals": "^2.1.2",
+    "@gramercytech/gx-componentkit": "^1.0.8",
+    "@vitejs/plugin-vue": "^5.1.4",
+    "archiver": "^7.0.1",
+    "chrome-launcher": "^1.1.2",
+    "concurrently": "^9.0.1",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.0",
+    "ink": "^5.0.1",
+    "ink-text-input": "^6.0.0",
+    "json-schema-faker": "^0.5.9",
+    "mkcert": "^3.2.0",
+    "nodemon": "^3.1.7",
+    "open": "^10.0.0",
+    "pinia": "^3.0.4",
+    "react": "^18.2.0",
+    "rollup-plugin-external-globals": "^0.12.0",
+    "shelljs": "^0.8.5",
+    "socket.io": "^4.8.0",
+    "socket.io-client": "^4.8.0",
+    "vite": "^5.4.8",
+    "vue": "^3.5.8",
+    "web-ext": "^8.2.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "concurrently": "^9.0.1",
+    "mkcert": "^3.2.0",
+    "nodemon": "^3.1.7",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}