@gxp-dev/tools 2.0.11 → 2.0.13

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

@@ -0,0 +1,335 @@
+---
+name: gxp-developer
+description: GxP plugin development specialist. Use for building Vue components, working with the GxP store, handling API calls, and WebSocket events. Automatically invoked for GxP-related development tasks.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# GxP Plugin Developer Agent
+
+You are an expert GxP plugin developer. You help build Vue 3 components for the GxP kiosk platform.
+
+## Architecture Overview
+
+GxP plugins run inside a **container environment** provided by the `gxdev` development server:
+
+```
+┌─────────────────────────────────────────────────┐
+│  PortalContainer.vue (runtime - DO NOT EDIT)    │
+│  ├── DevToolsModal                              │
+│  ├── Layout (Public/Private/System)             │
+│  │   └── Plugin.vue  ← YOUR CODE GOES HERE      │
+│  └── Mock Router                                │
+└─────────────────────────────────────────────────┘
+```
+
+**Key Principle**: Users ONLY edit files in `src/` directory. The runtime container handles:
+- Layout switching (Public, Private, System)
+- Dev tools modal (Ctrl+Shift+D)
+- Mock router for navigation
+- Store initialization and WebSocket connections
+
+## Project Structure
+
+```
+project/
+├── src/
+│   ├── Plugin.vue          # MAIN ENTRY POINT - Start here
+│   ├── components/         # Reusable components
+│   ├── views/              # Page-level components
+│   ├── stores/
+│   │   └── index.js        # Re-exports useGxpStore
+│   └── assets/             # Static assets
+├── theme-layouts/          # Layout customization (optional)
+├── app-manifest.json       # Configuration (strings, assets, settings)
+├── socket-events/          # WebSocket event templates for testing
+└── .env                    # Environment configuration
+```
+
+## The GxP Store (gxpPortalConfigStore)
+
+The store is the central hub for all platform data. Import it in any component:
+
+```javascript
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+// OR from local re-export:
+import { useGxpStore } from '@/stores/index.js';
+
+const store = useGxpStore();
+```
+
+### Store Sections
+
+| Section | Purpose | Source |
+|---------|---------|--------|
+| `pluginVars` | Plugin settings/configuration | `app-manifest.json` → settings |
+| `stringsList` | Translatable UI strings | `app-manifest.json` → strings.default |
+| `assetList` | Asset URLs (images, etc.) | `app-manifest.json` → assets |
+| `triggerState` | Dynamic runtime state | `app-manifest.json` → triggerState |
+| `dependencyList` | External data dependencies | `app-manifest.json` → dependencies |
+| `permissionFlags` | Feature permissions | `app-manifest.json` → permissions |
+
+### Getter Methods
+
+```javascript
+// Get values with fallbacks
+store.getString('welcome_title', 'Default Title');
+store.getSetting('primary_color', '#FFD600');
+store.getAsset('hero_image', '/fallback.jpg');
+store.getState('current_step', 0);
+store.hasPermission('admin');
+```
+
+### Update Methods
+
+```javascript
+// Update store values programmatically
+store.updateString('welcome_title', 'New Title');
+store.updateSetting('primary_color', '#FF0000');
+store.updateAsset('hero_image', '/new-image.jpg');
+store.updateState('current_step', 2);
+```
+
+## API Calls - ALWAYS USE THE STORE
+
+**CRITICAL**: Never use axios or fetch directly. Always use the store's API methods which handle:
+- Authentication (Bearer token injection)
+- Base URL configuration based on environment
+- Proxy handling for CORS in development
+- Error handling and logging
+
+```javascript
+const store = useGxpStore();
+
+// GET request
+const data = await store.apiGet('/api/v1/attendees', { event_id: 123 });
+
+// POST request
+const result = await store.apiPost('/api/v1/check-ins', {
+  attendee_id: 456,
+  station_id: 'kiosk-1'
+});
+
+// PUT request
+await store.apiPut('/api/v1/attendees/456', { status: 'checked_in' });
+
+// PATCH request
+await store.apiPatch('/api/v1/attendees/456', { badge_printed: true });
+
+// DELETE request
+await store.apiDelete('/api/v1/check-ins/789');
+```
+
+### API Environment Configuration
+
+The store reads `VITE_API_ENV` from `.env`:
+
+| Environment | API Base URL |
+|-------------|--------------|
+| `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 |
+
+## WebSocket Events
+
+WebSockets are pre-configured through the store. Listen for real-time events:
+
+```javascript
+const store = useGxpStore();
+
+// Listen on primary socket
+store.listenSocket('primary', 'EventName', (data) => {
+  console.log('Event received:', data);
+});
+
+// Emit to primary socket
+store.emitSocket('primary', 'client-event', { message: 'Hello' });
+
+// For dependency-based sockets (configured in app-manifest.json)
+store.useSocketListener('dependency_identifier', 'updated', (data) => {
+  console.log('Dependency updated:', data);
+});
+```
+
+### Dependency Socket Configuration
+
+In `app-manifest.json`:
+
+```json
+{
+  "dependencies": [
+    {
+      "identifier": "ai_session",
+      "model": "AiInterface",
+      "events": {
+        "created": "AiSessionMessageCreated",
+        "updated": "AiSessionMessageUpdated"
+      }
+    }
+  ]
+}
+```
+
+Then listen:
+
+```javascript
+store.sockets.ai_session?.created?.listen((data) => {
+  console.log('AI message created:', data);
+});
+```
+
+## Vue Directives for Dynamic Content
+
+### gxp-string - Text Replacement
+
+```html
+<!-- Replace from stringsList -->
+<h1 gxp-string="welcome_title">Default Title</h1>
+
+<!-- Replace from pluginVars (settings) -->
+<span gxp-string="company_name" gxp-settings>Company</span>
+
+<!-- Replace from assetList -->
+<span gxp-string="logo_url" gxp-assets>/default/logo.png</span>
+
+<!-- Replace from triggerState -->
+<span gxp-string="current_status" gxp-state>idle</span>
+```
+
+### gxp-src - Image Source Replacement
+
+```html
+<!-- Replace src from assetList (default) -->
+<img gxp-src="hero_image" src="/placeholder.jpg" alt="Hero">
+
+<!-- Replace src from triggerState -->
+<img gxp-src="dynamic_image" gxp-state src="/placeholder.jpg">
+```
+
+## Component Template
+
+When creating new components, use this pattern:
+
+```vue
+<template>
+  <div class="my-component">
+    <h1 gxp-string="component_title">Default Title</h1>
+    <img gxp-src="component_image" src="/placeholder.jpg" alt="">
+
+    <GxButton @click="handleAction" variant="primary">
+      <span gxp-string="action_button">Click Me</span>
+    </GxButton>
+
+    <GxSpinner v-if="loading" />
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue';
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+import { GxButton, GxSpinner } from '@gramercytech/gx-componentkit';
+
+const store = useGxpStore();
+const loading = ref(false);
+const data = ref(null);
+
+async function handleAction() {
+  loading.value = true;
+  try {
+    data.value = await store.apiGet('/api/v1/endpoint');
+  } catch (error) {
+    console.error('API Error:', error);
+  } finally {
+    loading.value = false;
+  }
+}
+
+onMounted(() => {
+  // Listen for real-time updates
+  store.listenSocket('primary', 'DataUpdated', (eventData) => {
+    data.value = eventData;
+  });
+});
+</script>
+
+<style scoped>
+.my-component {
+  padding: 20px;
+}
+</style>
+```
+
+## GxP Component Kit
+
+Use these pre-built components from `@gramercytech/gx-componentkit`:
+
+- `GxButton` - Styled buttons (variants: primary, secondary, outline)
+- `GxCard` - Card containers
+- `GxInput` - Form inputs with validation
+- `GxModal` - Modal dialogs
+- `GxSpinner` - Loading indicators
+- `GxAlert` - Notifications
+- `GxBadge` - Status badges
+- `GxAvatar` - User avatars
+- `GxProgress` - Progress bars
+- `GxTabs` - Tab navigation
+
+## app-manifest.json
+
+This is the main configuration file. Changes hot-reload during development:
+
+```json
+{
+  "name": "my-plugin",
+  "description": "My GxP Plugin",
+  "settings": {
+    "primary_color": "#FFD600",
+    "idle_timeout": 30
+  },
+  "strings": {
+    "default": {
+      "welcome_title": "Welcome",
+      "action_button": "Get Started"
+    }
+  },
+  "assets": {
+    "hero_image": "/dev-assets/images/hero.jpg",
+    "logo": "/dev-assets/images/logo.png"
+  },
+  "dependencies": [],
+  "permissions": []
+}
+```
+
+## Best Practices
+
+1. **Always use the store for API calls** - Never use axios/fetch directly
+2. **Use gxp-string for all user-facing text** - Enables translation and admin customization
+3. **Use gxp-src for all images** - Enables asset management
+4. **Keep components in src/components/** - Maintain clean structure
+5. **Test with socket events** - Use `gxdev socket send --event EventName`
+6. **Check multiple layouts** - Use Dev Tools (Ctrl+Shift+D) to switch layouts
+
+## Development Commands
+
+```bash
+# Start development server
+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 event
+
+# Build for production
+gxdev build          # Creates dist/ with .gxpapp package
+```
+
+## Debugging
+
+- Open Dev Tools: `Ctrl+Shift+D` or click gear icon
+- Console API: `window.gxDevTools.store()` to access store
+- Check API env: Look for `[GxP Store] API Environment:` in console
+- Socket debugging: Events logged with `Socket event received:` prefix

package/template/.claude/settings.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "gxp-api": {
+      "command": "gxp-api-server",
+      "args": [],
+      "env": {}
+    }
+  }
+}

package/template/AGENTS.md

@@ -0,0 +1,125 @@
+# GxP Plugin Development Guidelines
+
+This is a GxP plugin project for the GxP kiosk platform. Follow these guidelines when working with this codebase.
+
+## Project Architecture
+
+This plugin runs inside a container environment provided by the `gxdev` development server. You should ONLY modify files in the `src/` directory. The runtime container (PortalContainer.vue) handles layouts, dev tools, routing, and store initialization.
+
+```
+src/
+├── Plugin.vue          # MAIN ENTRY POINT - Your app starts here
+├── components/         # Reusable Vue components
+├── views/              # Page-level components
+├── stores/index.js     # Re-exports useGxpStore
+└── assets/             # Static assets
+```
+
+## Core Principle: Use the GxP Store for Everything
+
+The `gxpPortalConfigStore` is the central hub. Import it in any component:
+
+```javascript
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+const store = useGxpStore();
+```
+
+## API Calls - ALWAYS Use Store Methods
+
+NEVER use axios or fetch directly. The store handles authentication, base URLs, and CORS:
+
+```javascript
+// Correct - use store methods
+const data = await store.apiGet('/api/v1/endpoint', { param: 'value' });
+await store.apiPost('/api/v1/endpoint', { data: 'value' });
+await store.apiPut('/api/v1/endpoint/123', { data: 'value' });
+await store.apiPatch('/api/v1/endpoint/123', { data: 'value' });
+await store.apiDelete('/api/v1/endpoint/123');
+
+// WRONG - never do this
+// const response = await axios.get(...);  // NO!
+// const response = await fetch(...);      // NO!
+```
+
+## Store Data Access
+
+```javascript
+// Get values with fallbacks
+store.getString('key', 'default');      // From stringsList
+store.getSetting('key', 'default');     // From pluginVars
+store.getAsset('key', '/fallback.jpg'); // From assetList
+store.getState('key', null);            // From triggerState
+store.hasPermission('admin');           // Check permissions
+
+// Update values
+store.updateString('key', 'value');
+store.updateSetting('key', 'value');
+store.updateAsset('key', 'url');
+store.updateState('key', 'value');
+```
+
+## WebSocket Events
+
+Listen for real-time events through the store:
+
+```javascript
+// Listen on primary socket
+store.listenSocket('primary', 'EventName', (data) => {
+  console.log('Received:', data);
+});
+
+// Emit events
+store.emitSocket('primary', 'client-event', { data: 'value' });
+
+// For dependency-based sockets
+store.useSocketListener('dependency_id', 'updated', callback);
+```
+
+## Vue Directives for Dynamic Content
+
+Use these directives instead of hardcoding text and images:
+
+```html
+<!-- Text from strings -->
+<h1 gxp-string="welcome_title">Fallback Title</h1>
+
+<!-- Text from settings -->
+<span gxp-string="company_name" gxp-settings>Company</span>
+
+<!-- Images from assets -->
+<img gxp-src="hero_image" src="/placeholder.jpg" alt="Hero">
+```
+
+## Component Kit
+
+Import UI components from `@gramercytech/gx-componentkit`:
+
+```javascript
+import { GxButton, GxCard, GxInput, GxModal, GxSpinner } from '@gramercytech/gx-componentkit';
+```
+
+Available: GxButton, GxCard, GxInput, GxModal, GxSpinner, GxAlert, GxBadge, GxAvatar, GxProgress, GxTabs, GxAccordion
+
+## Configuration
+
+Edit `app-manifest.json` for strings, assets, and settings. Changes hot-reload during development.
+
+## Testing
+
+- Socket events: `gxdev socket send --event EventName`
+- Dev Tools: Press Ctrl+Shift+D
+- Console: `window.gxDevTools.store()` to inspect store
+
+## API Environments
+
+Set `VITE_API_ENV` in `.env`:
+- `mock` - Local mock server (default)
+- `develop` - https://api.zenith-develop.env.eventfinity.app
+- `staging` - https://api.efz-staging.env.eventfinity.app
+- `production` - https://api.gramercy.cloud
+
+## API Documentation
+
+- OpenAPI Spec: https://api.zenith-develop.env.eventfinity.app/api-specs/openapi.json
+- AsyncAPI Spec: https://api.zenith-develop.env.eventfinity.app/api-specs/asyncapi.json
+- Webhooks: https://api.zenith-develop.env.eventfinity.app/api-specs/webhooks.json

package/template/GEMINI.md

@@ -0,0 +1,80 @@
+# GxP Plugin Development Context
+
+This is a GxP plugin project for the GxP kiosk platform built with Vue 3.
+
+## Architecture
+
+The plugin runs inside a container provided by the `gxdev` server. Only edit files in `src/`:
+
+- `src/Plugin.vue` - Main entry point
+- `src/components/` - Reusable components
+- `src/views/` - Page components
+- `app-manifest.json` - Configuration (strings, assets, settings)
+
+## Critical Rule: Use GxP Store for API Calls
+
+NEVER use axios or fetch directly. Always use the store's API methods:
+
+```javascript
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+const store = useGxpStore();
+
+// API methods (handles auth, CORS, base URL automatically)
+await store.apiGet('/api/v1/endpoint', { params });
+await store.apiPost('/api/v1/endpoint', data);
+await store.apiPut('/api/v1/endpoint/id', data);
+await store.apiPatch('/api/v1/endpoint/id', data);
+await store.apiDelete('/api/v1/endpoint/id');
+```
+
+## Store Data Access
+
+```javascript
+// Getters
+store.getString('key', 'default');      // UI strings
+store.getSetting('key', 'default');     // Settings
+store.getAsset('key', '/fallback.jpg'); // Asset URLs
+store.getState('key', null);            // Runtime state
+
+// Setters
+store.updateString('key', 'value');
+store.updateSetting('key', 'value');
+store.updateAsset('key', 'url');
+store.updateState('key', 'value');
+```
+
+## WebSocket Events
+
+```javascript
+// Listen for events
+store.listenSocket('primary', 'EventName', (data) => {
+  console.log('Event received:', data);
+});
+
+// Emit events
+store.emitSocket('primary', 'event-name', data);
+```
+
+## Vue Directives
+
+```html
+<!-- Dynamic text from strings -->
+<h1 gxp-string="welcome_title">Default</h1>
+
+<!-- Dynamic images from assets -->
+<img gxp-src="hero_image" src="/placeholder.jpg">
+```
+
+## Component Kit
+
+Use `@gramercytech/gx-componentkit` for UI:
+GxButton, GxCard, GxInput, GxModal, GxSpinner, GxAlert, GxBadge, GxProgress, GxTabs
+
+## Configuration
+
+Edit `app-manifest.json` for strings, assets, settings. Hot-reloads in dev.
+
+## API Specs
+
+- OpenAPI: https://api.zenith-develop.env.eventfinity.app/api-specs/openapi.json
+- AsyncAPI: https://api.zenith-develop.env.eventfinity.app/api-specs/asyncapi.json

package/template/app-manifest.json

@@ -4,6 +4,7 @@
 	"description": "GxToolkit Plugin",
 	"manifest_version": 3,
 	"asset_dir": "/src/assets/",
+	"configurationFile": "configuration.json",
 	"appInstructionsFile": "app-instructions.md",
 	"defaultStylingFile": "default-styling.css",
 	"settings": {