@gxp-dev/tools 2.0.71 → 2.0.72

package/template/README.md

@@ -1,349 +1,314 @@
 # GxP Plugin Project
 
-This project was created with `@gxp-dev/tools` and includes the `@gramercytech/gx-componentkit` component library for rapid kiosk development.
+This project was scaffolded by `@gxp-dev/tools` and includes the `@gramercytech/gx-componentkit` component library for rapid kiosk/plugin development.
 
 ## Quick Start
 
 ```bash
-# Start HTTP development server
-npm run dev-http
-
-# Start HTTPS development server with Socket.IO
-npm run dev
-
-# Build for production
-npm run build
+npm install
+npm run dev-http          # HTTP dev server (or `npm run dev` for HTTPS + Socket.IO)
 ```
 
+Open `http://localhost:3060`. Press `Ctrl+Shift+D` for the in-browser Dev Tools.
+
 ## Project Structure
 
 ```
 your-project/
 ├── src/
-│   ├── Plugin.vue           # Your app entry point (customize this!)
-│   ├── DemoPage.vue         # Example component
-│   ├── components/          # Your custom components
-│   ├── composables/         # Your custom logic
-│   ├── stores/              # Pinia stores
-│   │   └── index.js         # Store setup
-│   └── socket-events/       # Socket event templates
-├── theme-layouts/           # Layout templates (System, Private, Public)
-│   ├── SystemLayout.vue
-│   ├── PrivateLayout.vue
-│   ├── PublicLayout.vue
-│   └── AdditionalStyling.css
-├── dev-assets/              # Development placeholder images
-├── socket-events/           # Socket event JSON files for simulation
-├── main.js                  # Development entry point
-├── vite.config.js           # Vite build configuration
-├── app-manifest.json        # Plugin manifest
-├── index.html               # Development HTML template
-└── .env                     # Environment configuration
+│   ├── Plugin.vue             # Your app entry point (edit this!)
+│   ├── DemoPage.vue           # Example component — strings/assets/socket demo
+│   ├── public/                # Static assets, served at /src/public/*
+│   └── stores/
+│       └── index.js           # Pinia store setup
+├── theme-layouts/             # System/Private/Public layout templates
+├── dev-assets/images/         # Placeholder images for dev
+├── socket-events/             # JSON event templates for simulation
+├── tests/                     # Vitest tests (add more as needed)
+├── scripts/                   # Browser extension launch/pack scripts
+├── .githooks/pre-commit       # Prettier + ESLint + gxdev lint on staged files
+├── app-manifest.json          # Plugin metadata + default strings/settings/assets
+├── app-instructions.md        # End-user onboarding — shown on install
+├── configuration.json         # Admin-panel configuration form (templating schema)
+├── vite.extend.js             # Optional Vite config extension (aliases/plugins/define)
+├── eslint.config.js           # ESLint flat config (JS + Vue)
+├── .prettierrc                # Prettier config
+└── .env                       # Environment variables
 ```
 
-## How It Works
+## How it works
 
-### Plugin.vue - Your App Entry Point
+### `src/Plugin.vue` — your entry point
 
-`src/Plugin.vue` is the root component of your application. During development, it's wrapped by the toolkit's PortalContainer (which emulates the GxP platform). In production, the platform loads your Plugin.vue directly.
+During development, the toolkit wraps Plugin.vue in `PortalContainer.vue`, which emulates the live GxP platform. In production the platform loads Plugin.vue directly. The platform injects these props:
 
 ```vue
-<template>
-	<div class="my-plugin">
-		<h1>{{ stringsList?.welcome_text || "Welcome!" }}</h1>
-		<!-- Your custom content here -->
-	</div>
-</template>
-
 <script setup>
-// Props injected by the platform
 const props = defineProps({
-	pluginVars: Object, // Custom variables from admin panel
-	dependencyList: Object, // Selected dependencies
-	assetUrls: Object, // Asset URLs (signed URLs for images, etc.)
+	pluginVars: Object, // Settings configured per-install
+	dependencyList: Object, // Linked API dependencies
+	assetUrls: Object, // Resolved asset URLs
 	stringsList: Object, // Localized strings
-	permissionFlags: Array, // Permission flags
+	permissionFlags: Array, // Granted permissions
 	theme: Object, // Theme configuration
-	router: Object, // Platform router for navigation
+	router: Object, // Platform router
 })
 </script>
 ```
 
-### Theme Layouts
-
-The `theme-layouts/` directory contains layout templates that wrap your Plugin component. The platform uses these to provide consistent UI structure:
-
-- **SystemLayout.vue** - System-level pages (errors, maintenance)
-- **PrivateLayout.vue** - Authenticated user pages
-- **PublicLayout.vue** - Public-facing pages
-
-You can customize these layouts to match your kiosk's design.
-
-## Development
-
-### Available Scripts
-
-| Script                    | Description                           |
-| ------------------------- | ------------------------------------- |
-| `npm run dev`             | Start HTTPS dev server with Socket.IO |
-| `npm run dev-app`         | Start HTTPS dev server only           |
-| `npm run dev-http`        | Start HTTP dev server (no SSL)        |
-| `npm run build`           | Build for production                  |
-| `npm run setup-ssl`       | Generate SSL certificates             |
-| `npm run socket:list`     | List available socket events          |
-| `npm run socket:send`     | Send test socket events               |
-| `npm run assets:list`     | List development assets               |
-| `npm run assets:init`     | Initialize asset directories          |
-| `npm run assets:generate` | Generate placeholder images           |
-
-### Dev Tools Modal
-
-During development, press **Ctrl+Shift+D** (or **Cmd+Shift+D** on Mac) to open the Dev Tools Modal. You can also click the gear icon in the bottom-right corner.
-
-The Dev Tools Modal provides:
+### GxP directives
 
-1. **Store Inspector** - View and edit store state:
-   - `pluginVars` - Custom variables
-   - `stringsList` - Localized strings
-   - `assetList` - Asset URLs
-   - `triggerState` - Trigger states
-   - `dependencyList` - Dependencies
+Bind template text and asset sources directly to the datastore — values are editable live from the Dev Tools:
 
-2. **Layout Switcher** - Toggle between System, Private, and Public layouts
-
-3. **Socket Simulator** - Send test socket events to your app
+```vue
+<!-- text from strings.default -->
+<h1 gxp-string="welcome_title">Welcome</h1>
 
-4. **Mock Data Editor** - Edit theme colors, navigation items, user session, and permissions
+<!-- text from settings (pluginVars) -->
+<code gxp-settings gxp-string="primary_color">#FFD600</code>
 
-You can also control dev tools from the browser console:
+<!-- text from triggerState -->
+<code gxp-state gxp-string="current_status">idle</code>
 
-```javascript
-window.gxDevTools.open() // Open modal
-window.gxDevTools.close() // Close modal
-window.gxDevTools.toggle() // Toggle modal
+<!-- swap the image src from assets -->
+<img gxp-src="hero_image" src="/src/public/hero.jpg" />
 ```
 
-### Environment Variables
+### Theme layouts
 
-Configure your development environment in `.env`:
+`theme-layouts/` wraps your plugin. Customize to match your kiosk's design:
 
-```bash
-# Development server port
-VITE_DEV_PORT=3060
+- **SystemLayout.vue** — system pages (errors, maintenance)
+- **PrivateLayout.vue** — authenticated pages
+- **PublicLayout.vue** — public-facing pages
 
-# Socket.IO server port
-VITE_SOCKET_PORT=3069
+## npm scripts
 
-# SSL certificates (if using HTTPS)
-VITE_SSL_CERT=.certs/localhost.pem
-VITE_SSL_KEY=.certs/localhost-key.pem
-```
+| Script                                                                             | What it does                                   |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `npm run dev`                                                                      | HTTPS dev server + Socket.IO + interactive TUI |
+| `npm run dev-app`                                                                  | HTTPS dev server only                          |
+| `npm run dev-http`                                                                 | HTTP dev server (no SSL)                       |
+| `npm run build`                                                                    | Production build → `dist/<name>.gxpapp`        |
+| `npm run test`                                                                     | Run Vitest once                                |
+| `npm run test:watch`                                                               | Vitest in watch mode                           |
+| `npm run lint`                                                                     | Run `gxdev lint --all` (config/manifest JSON)  |
+| `npm run lint:js`                                                                  | Run ESLint on JS/Vue files                     |
+| `npm run format`                                                                   | Run Prettier across the project                |
+| `npm run setup-ssl`                                                                | Generate SSL certificates via mkcert           |
+| `npm run socket:list`                                                              | List available socket events                   |
+| `npm run socket:send`                                                              | Send a test socket event                       |
+| `npm run assets:list` / `assets:init` / `assets:generate`                          | Manage dev assets                              |
+| `npm run datastore:list` / `datastore:add` / `datastore:scan` / `datastore:config` | Manage the GxP datastore                       |
 
-## Platform Props
+## Development tooling
 
-Your Plugin.vue component receives these props from the platform:
+### In-browser Dev Tools
 
-### pluginVars
-
-Custom variables configured in the admin panel:
-
-```javascript
-const { pluginVars } = props
-console.log(pluginVars.primary_color) // "#FFD600"
-console.log(pluginVars.projectId) // 39
-```
+Press **Ctrl+Shift+D** (or Cmd+Shift+D on macOS) to open:
 
-### assetUrls
+1. **Store Inspector** — view/edit `pluginVars` (settings), `stringsList`, `assetList`, `triggerState`, `dependencyList`. Hover a key to highlight every matching element; double-click a value to edit.
+2. **Layout Switcher** — swap between Public / Private / System layouts.
+3. **Socket Simulator** — fire test socket events.
+4. **Mock Data Editor** — edit theme colors, nav, session, permissions.
 
-URLs for configured assets:
+Console API:
 
-```vue
-<img :src="assetUrls.main_logo" alt="Logo" />
-<img :src="assetUrls.background_image" alt="Background" />
+```js
+window.gxDevTools.open() // open
+window.gxDevTools.close() // close
+window.gxDevTools.toggle() // toggle
+window.gxDevTools.store() // grab the Pinia store
 ```
 
-### stringsList
+### Pre-commit hook
 
-Localized strings:
+The `.githooks/pre-commit` hook runs on every `git commit` (auto-enabled by the `prepare` npm script):
 
-```vue
-<h1>{{ stringsList.welcome_text }}</h1>
-<p>{{ stringsList.instruction_text }}</p>
-```
+1. **Prettier** formats every staged JS/TS/Vue/CSS/JSON/MD/YAML/HTML file.
+2. **ESLint** fixes every staged JS/Vue file.
+3. **`gxdev lint`** validates staged `configuration.json` / `app-manifest.json` against the GxP templating schema.
 
-### theme
+Any non-zero exit aborts the commit. To stage fixes, ESLint and Prettier re-add their outputs automatically.
 
-Theme configuration (colors, fonts, etc.):
+### Linting config JSON
 
-```vue
-<GxThemeWrapper :theme="theme">
-  <!-- Your content inherits theme variables -->
-</GxThemeWrapper>
-```
+`gxdev lint` uses AJV + the GxP templating schema to validate:
 
-### router
+- **`configuration.json`** — the admin form definition (cards, fields, nested card_list / tabs_list structures).
+- **`app-manifest.json`** — plugin metadata, strings/settings/assets/triggerState shapes, dependency entries.
 
-Platform router for navigation (Inertia.js-style):
+Run manually with `npm run lint`, or point at a single file: `gxdev lint path/to/file.json`.
 
-```javascript
-// Basic navigation
-router.visit("/camera")
+### Writing tests
 
-// POST data to a route
-router.visit("/share", {
-	method: "post",
-	data: { image: photoUrl, caption: "My photo!" },
-})
+Tests live under `tests/` and run with Vitest:
 
-// Navigation with options
-router.visit("/results", {
-	preserveScroll: true,
-	preserveState: true,
-	replace: true,
-	onStart: () => {},
-	onFinish: () => {},
-	onError: (errors) => {},
+```js
+import { describe, it, expect } from "vitest"
+import { mount } from "@vue/test-utils"
+import DemoPage from "@/DemoPage.vue"
+
+describe("DemoPage", () => {
+	it("renders", () => {
+		const wrapper = mount(DemoPage)
+		expect(wrapper.exists()).toBe(true)
+	})
 })
 ```
 
-## GX ComponentKit
+Scaffold a new test with the MCP tool `test_scaffold_component_test` (via an AI assistant) or write them by hand. Run with `npm run test` or `npm run test:watch`.
 
-This project includes `@gramercytech/gx-componentkit` with pre-built components:
+### Customizing the Vite config
 
-### Page Components
+Don't replace `vite.config.js` — the toolkit serves one from its runtime. Instead, edit `vite.extend.js` at the project root. Its exports are deep-merged into the runtime config via `mergeConfig` (plugins concatenate, `resolve.alias` / `define` merge key-by-key):
 
-- `GxPageStart` - Welcome/start screen with idle timeout
-- `GxPageInstructions` - Instruction display page
-- `GxPageCamera` - Camera capture interface
-- `GxPageResults` - Results display page
-- `GxPageShare` - Social sharing interface
-- `GxPageFinal` - Thank you/completion page
-- `GxPageLoading` - Loading overlay
+```js
+import path from "path"
+import { fileURLToPath } from "url"
 
-### UI Components
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
-- `GxModal` - Customizable modal dialogs
-- `GxCountdown` - Timer/countdown component
-- `GxVideoPlayer` - Video player with custom controls
-- `GxThemeWrapper` - Theme provider component
+export default {
+	resolve: {
+		alias: {
+			"@components": path.resolve(__dirname, "src/components"),
+			"@pages": path.resolve(__dirname, "src/pages"),
+		},
+	},
+	// plugins: [somePlugin()],
+	// define: { "import.meta.env.VITE_MY_FLAG": JSON.stringify("value") },
+}
+```
 
-### Composables
+## Environment variables
+
+Set in `.env`:
+
+| Variable                             | Default            | Description                                                                      |
+| ------------------------------------ | ------------------ | -------------------------------------------------------------------------------- |
+| `NODE_PORT`                          | `3060`             | Dev server port                                                                  |
+| `SOCKET_IO_PORT`                     | `3069`             | Socket.IO server port                                                            |
+| `COMPONENT_PATH`                     | `./src/Plugin.vue` | Main component path                                                              |
+| `USE_HTTPS`                          | `true`             | Enable HTTPS                                                                     |
+| `CERT_PATH` / `KEY_PATH`             |                    | SSL cert paths (auto-set by `setup-ssl`)                                         |
+| `USE_LOCAL_INDEX` / `USE_LOCAL_MAIN` |                    | Opt into local copies of `index.html` / `main.js`                                |
+| `API_ENV`                            | `mock`             | API environment (`mock`, `local`, `develop`, `testing`, `staging`, `production`) |
+| `MOCK_API_ENABLED`                   | `false`            | Mount the local mock API at `/api/*`                                             |
+
+## `app-manifest.json` overview
+
+Plugin metadata + default datastore values loaded by the platform on install:
+
+```json
+{
+	"name": "My Plugin",
+	"version": "1.0.0",
+	"manifest_version": 3,
+	"asset_dir": "/src/public",
+	"configurationFile": "configuration.json",
+	"appInstructionsFile": "app-instructions.md",
+	"defaultStylingFile": "default-styling.css",
+	"settings": { "primary_color": "#FFD600" },
+	"strings": { "default": { "welcome_title": "Welcome" } },
+	"assets": { "main_logo": "/src/public/logo.png" },
+	"triggerState": { "current_status": "idle" },
+	"dependencies": [],
+	"permissions": []
+}
+```
 
-- `useMedia()` - Camera, video, and audio utilities
-- `useAnimations()` - Animation helpers
-- `useScanning()` - Barcode/QR scanning
-- `useErrors()` - Error state management
+Run `gxdev extract-config` to scan `src/` for directives and store calls and merge new keys into the manifest automatically.
+
+## `configuration.json` — admin form
+
+This file defines the configuration form operators see when installing/configuring your plugin in the admin panel. It follows the GxP templating system (`additionalTabs` → cards → fields). A minimal example:
+
+```json
+{
+	"additionalTabs": [
+		{
+			"type": "card_list",
+			"cards": [
+				{
+					"type": "fields_list",
+					"title": "General",
+					"fieldsList": [
+						{ "type": "text", "name": "company_name", "label": "Company" },
+						{
+							"type": "colorPicker",
+							"name": "primary_color",
+							"label": "Brand color"
+						}
+					]
+				}
+			]
+		}
+	]
+}
+```
 
-### Usage Example
+Full reference: [docs.gxp.dev/gx-devtools/app-manifest](https://docs.gxp.dev/gx-devtools/app-manifest) and the platform templating docs. Validate any time with `gxdev lint configuration.json`.
 
-```vue
-<script setup>
-import {
-	GxModal,
-	GxCountdown,
-	GxVideoPlayer,
-	useMedia,
-} from "@gramercytech/gx-componentkit"
-
-const { startCamera, takePhoto } = useMedia()
-</script>
+## GX ComponentKit
 
-<template>
-	<GxCountdown :duration="30" @finished="handleFinished" />
-	<GxVideoPlayer :src="videoUrl" @play="handlePlay" />
-</template>
-```
+This project includes `@gramercytech/gx-componentkit`:
 
-## Custom Styling
+- **Pages** — `GxPageStart`, `GxPageInstructions`, `GxPageCamera`, `GxPageResults`, `GxPageShare`, `GxPageFinal`, `GxPageLoading`
+- **UI** — `GxModal`, `GxCountdown`, `GxVideoPlayer`, `GxThemeWrapper`
+- **Composables** — `useMedia`, `useAnimations`, `useScanning`, `useErrors`
 
-Theme CSS variables are automatically available:
+Theme CSS variables are auto-injected:
 
 ```css
 .my-component {
 	background: var(--gx-primary-color);
 	color: var(--gx-text-color);
-	border: 2px solid var(--gx-primary-color);
 }
 ```
 
-## Socket Events
-
-Test real-time features with socket simulation:
+## Socket events
 
 ```bash
-# List available socket events
 npm run socket:list
-
-# Send a socket event
 npm run socket:send
-
-# Send to specific channel
 gxdev socket send --event SocialStreamPostCreated --identifier "stream_123"
 ```
 
-Socket event templates are in `socket-events/` directory. Add your own JSON files to simulate custom events.
+Event templates live in `socket-events/` — add JSON files to simulate custom events.
 
-## Asset Management
+## Assets
 
 ```bash
-# List all development assets
 npm run assets:list
-
-# Initialize asset directories
 npm run assets:init
-
-# Generate placeholder images (requires ImageMagick)
 npm run assets:generate
 gxdev assets generate --size 800x600 --name product-image
-gxdev assets generate --name logo --size 200x200 --color "#FF5722" --text "My Logo"
 ```
 
-### ImageMagick Installation
+Requires ImageMagick:
 
 ```bash
-# macOS
-brew install imagemagick
-
-# Ubuntu/Debian
-sudo apt-get install imagemagick
-
-# Windows - download from https://imagemagick.org/script/download.php
+brew install imagemagick            # macOS
+sudo apt-get install imagemagick    # Ubuntu/Debian
 ```
 
-## Building for Production
+## Building for production
 
 ```bash
 npm run build
 ```
 
-This creates a `dist/` folder with:
-
-- `plugin.es.js` - Your compiled plugin (ES module)
-- `style.css` - Compiled styles
-
-The build excludes development files (main.js, index.html) and externalizes Vue (the platform provides it).
-
-## Project Architecture
-
-```
-Plugin.vue (your entry point)
-├── imports YourHeader.vue
-├── imports YourContent.vue
-│   ├── imports ProductList.vue
-│   ├── imports ShoppingCart.vue
-│   └── imports YourModal.vue
-└── imports YourFooter.vue
-```
-
-Everything imported into Plugin.vue (directly or indirectly) is included in the build. The platform loads your Plugin.vue and injects the necessary props.
+Produces `dist/<plugin-name>.gxpapp` — a zip containing compiled `plugin.es.js`, `style.css`, `app-manifest.json`, assets, and any bundled files referenced by the manifest. Upload this to the GxP plugin registry.
 
-## Learn More
+## Learn more
 
-- [GX ComponentKit Documentation](https://github.com/gramercytech/gx-componentkit)
-- [GxP Platform Documentation](https://www.gramercytech.com/gxp)
-- [Vue 3 Documentation](https://vuejs.org/)
-- [Vite Documentation](https://vitejs.dev/)
+- **Platform docs** — [docs.gxp.dev](https://docs.gxp.dev)
+- **CLI reference** — [docs.gxp.dev/gx-devtools/cli-reference](https://docs.gxp.dev/gx-devtools/cli-reference)
+- **ComponentKit** — [docs.gxp.dev/gx-uikit](https://docs.gxp.dev/gx-uikit)
+- **Vue 3** — [vuejs.org](https://vuejs.org/)
+- **Vite** — [vitejs.dev](https://vitejs.dev/)
 
 ## Support
 
-For questions about this template or gx-componentkit integration, please contact the development team or check the documentation links above.
+Contact the Gramercy development team or open an issue in the plugin repo.

package/template/app-instructions.md

@@ -0,0 +1,91 @@
+# App Instructions
+
+> **👋 Plugin developer — replace this file.**
+>
+> Everything in this file is shown to **end users** on the GxP platform the first
+> time they install your plugin. Treat it like the "About" screen of your app:
+> what it does, how to use it, what to expect. Strip out the template sections
+> below and write for your audience, not for developers.
+>
+> _Delete this callout before shipping._
+
+---
+
+## About GxP plugins
+
+GxP plugins are self-contained Vue apps that run inside the Gramercy Experience
+Platform. Your plugin gets:
+
+- A slice of platform UI to render into (Public, Private, or System layout).
+- A reactive **datastore** populated at runtime with strings, settings, assets,
+  permissions, and feature flags configured by the platform operator.
+- **Sockets** for real-time events (default channel: `primary`).
+- Optional **dependencies** — models and event streams provided by other
+  plugins or platform modules.
+
+Plugins are packaged as a `.gxpapp` bundle and distributed through the GxP
+plugin registry.
+
+## Getting started (for developers)
+
+```bash
+# Install the toolkit CLI (already listed as a devDependency)
+npm install
+
+# Start the dev server (HTTPS by default)
+npm run dev
+
+# …or launch the interactive TUI
+gxdev
+```
+
+Then open the browser to the dev URL printed in the console.
+
+**Key files:**
+
+| File                  | What it does                                                         |
+| --------------------- | -------------------------------------------------------------------- |
+| `src/Plugin.vue`      | Your app's entry point. Rendered by the platform.                    |
+| `app-manifest.json`   | Plugin metadata + default strings, settings, assets, permissions.    |
+| `src/public/`         | Static assets (images, fonts). Served at `/src/public/*`.            |
+| `vite.extend.js`      | Optional — extends the runtime Vite config (aliases, plugins, etc.). |
+| `app-instructions.md` | **This file.** Shown to end users — replace it.                      |
+| `configuration.json`  | Per-install configuration schema shown to operators.                 |
+| `default-styling.css` | Optional stylesheet bundled with the plugin.                         |
+
+**Dev tools:** press `Ctrl+Shift+D` in the running app to open the in-browser
+Store Inspector, layout switcher, socket simulator, and mock-data editor.
+
+## Building and packaging
+
+```bash
+npm run build     # produces dist/<plugin-name>.gxpapp
+```
+
+The `.gxpapp` file is what you upload to the GxP plugin registry.
+
+---
+
+## Template — end-user-facing content starts here
+
+> Everything below is placeholder copy. Replace it with your app's actual
+> user-facing content.
+
+### What is this plugin?
+
+_A one-or-two-sentence description of what the plugin does and why a user
+would install it._
+
+### How to use it
+
+1. _First step the user should take._
+2. _Second step._
+3. _…_
+
+### Frequently asked questions
+
+**Can I customize the colors or text?**
+_Answer that covers whatever your `configuration.json` exposes to operators._
+
+**Who do I contact for support?**
+_Your support contact / link._