gl-life-claude-zen 1.0.3 → 1.3.1

package/templates/test-site/README.md

@@ -0,0 +1,271 @@
+# Integration Test Website
+
+A lightweight, hot-reloading test site for stakeholder validation of UI components before production deployment.
+
+## Purpose
+
+This test site allows stakeholders to:
+- Preview UI components in isolation
+- Interact with components using realistic data
+- Validate behavior before production deployment
+- Test responsiveness across devices
+- Approve visual design and UX flows
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+cd test-site
+npm install
+```
+
+### 2. Run Development Server
+
+```bash
+npm run dev
+```
+
+The server will automatically allocate a port (default: 3000-3009 range) and display the URL.
+
+**Port Management Features:**
+- **Fixed Port Allocation**: Uses port 3000 by default, with automatic fallback to 3001-3009 if occupied
+- **Auto-Cleanup**: Automatically kills stale processes on the assigned port before starting
+- **Port Reuse**: Consistently uses the same port for a stable development experience
+- **Conflict Resolution**: Automatically finds an available port if the preferred port is in use
+
+Open the displayed URL (typically [http://localhost:3000](http://localhost:3000)) to view the test site.
+
+### 3. Add Your Components
+
+Edit `src/App.jsx` to import and render your components:
+
+```jsx
+// Import your component
+import { Button } from '../Agent/src/components/Button'
+
+function App() {
+  return (
+    <div className="demo-section">
+      <h2>Button Component Demo</h2>
+      <Button onClick={() => alert('Clicked!')}>
+        Click Me
+      </Button>
+    </div>
+  )
+}
+```
+
+## Available Scripts
+
+### `npm run dev`
+Starts the development server with:
+- **Port management**: Auto-allocates port from 3000-3009 range
+- **Hot reload**: Instant updates when you save files
+- **Auto-cleanup**: Kills stale processes before starting
+- **Graceful shutdown**: Releases port on Ctrl+C
+
+### `npm run dev:simple`
+Starts Vite server without port management (uses default Vite behavior).
+
+### `npm run build`
+Builds the site for production to the `dist/` folder.
+
+### `npm run preview`
+Preview the production build locally before deploying.
+
+### `npm run deploy`
+Builds and deploys the site to GitHub Pages.
+
+## Deployment to GitHub Pages
+
+### First-time Setup
+
+1. Create a GitHub repository for your project (if not already done)
+2. Enable GitHub Pages in repository settings:
+   - Go to Settings → Pages
+   - Source: Deploy from a branch
+   - Branch: Select `gh-pages` branch
+   - Click Save
+
+### Deploy Updates
+
+```bash
+npm run deploy
+```
+
+This will build the site and push it to the `gh-pages` branch automatically.
+
+Your test site will be available at:
+```
+https://<your-username>.github.io/<repo-name>/
+```
+
+## Sharing with Stakeholders
+
+### Option 1: GitHub Pages (Recommended)
+Deploy to GitHub Pages and share the URL. Updates are instant when you run `npm run deploy`.
+
+### Option 2: Local Network
+Run `npm run dev` and share your local IP address (find with `ipconfig` on Windows or `ifconfig` on Mac/Linux):
+```
+http://192.168.1.XXX:3000
+```
+
+### Option 3: Tunneling Service
+Use a service like ngrok to create a public URL for your local server:
+```bash
+npx ngrok http 3000
+```
+
+## Framework Support
+
+### React (Default)
+The template uses Vite + React with hot reload. No additional setup needed.
+
+### Vue
+To use Vue instead of React:
+
+1. Replace dependencies in `package.json`:
+```json
+{
+  "dependencies": {
+    "vue": "^3.3.4"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^4.5.0",
+    "vite": "^5.0.8"
+  }
+}
+```
+
+2. Update `vite.config.js`:
+```js
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  // ...rest of config
+})
+```
+
+3. Rename `src/main.jsx` → `src/main.js` and update content:
+```js
+import { createApp } from 'vue'
+import App from './App.vue'
+import './index.css'
+
+createApp(App).mount('#app')
+```
+
+### Svelte
+To use Svelte:
+
+1. Replace dependencies in `package.json`:
+```json
+{
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^3.0.0",
+    "svelte": "^4.2.8",
+    "vite": "^5.0.8"
+  }
+}
+```
+
+2. Update `vite.config.js`:
+```js
+import { defineConfig } from 'vite'
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+
+export default defineConfig({
+  plugins: [svelte()],
+  // ...rest of config
+})
+```
+
+3. Rename files to `.svelte` and update imports.
+
+## Best Practices
+
+### 1. Use Realistic Data
+Don't use placeholder text. Use realistic data that stakeholders will recognize:
+```jsx
+<UserCard
+  name="John Smith"
+  email="john.smith@company.com"
+  role="Product Manager"
+/>
+```
+
+### 2. Show Multiple States
+Demonstrate different component states:
+```jsx
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button disabled>Disabled</Button>
+```
+
+### 3. Test Edge Cases
+Show how components handle edge cases:
+```jsx
+<UserName name="Really Long Name That Might Wrap" />
+<UserName name="" /> {/* Empty state */}
+<ErrorMessage>Something went wrong!</ErrorMessage>
+```
+
+### 4. Group by Feature
+Organize components by feature or user flow:
+```jsx
+<section className="login-flow">
+  <h2>Login Flow</h2>
+  <LoginForm />
+  <ForgotPassword />
+  <SignUpLink />
+</section>
+```
+
+### 5. Add Annotations
+Explain what stakeholders should validate:
+```jsx
+<div className="demo-section">
+  <h2>Shopping Cart</h2>
+  <p><strong>Validation Points:</strong></p>
+  <ul>
+    <li>Items can be added/removed</li>
+    <li>Quantity updates recalculate total</li>
+    <li>Discount codes apply correctly</li>
+  </ul>
+  <ShoppingCart items={mockCartItems} />
+</div>
+```
+
+## Troubleshooting
+
+### Components Not Found
+If your components can't be imported:
+- Check the import path is correct relative to `test-site/src/`
+- Ensure components are exported properly
+- Verify file extensions match (.jsx, .tsx, etc.)
+
+### Styles Not Working
+- Import component CSS files alongside components
+- Check that Tailwind/styled-components are configured if used
+- Verify CSS module naming conventions
+
+### Hot Reload Issues
+- Save files to trigger reload
+- Check terminal for build errors
+- Restart dev server: `Ctrl+C` then `npm run dev`
+
+## Tips for Stakeholder Review
+
+1. **Schedule a live demo session** - Walk through components together
+2. **Record a video** - Show interactions and flows
+3. **Create a checklist** - What needs approval on each component
+4. **Collect feedback** - Add a feedback form or use GitHub Issues
+5. **Version deployments** - Use git tags to track approved versions
+
+## License
+
+This template is part of the gl-life-claude-zen package and follows the same license as the parent project.

package/templates/test-site/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Integration Test Site - Component Preview</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/templates/test-site/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "integration-test-site",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Integration test website for stakeholder validation of UI components",
+  "scripts": {
+    "dev": "node server.js",
+    "dev:simple": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "deploy": "npm run build && npx gh-pages -d dist"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@vitejs/plugin-react": "^4.2.1",
+    "gh-pages": "^6.1.1",
+    "vite": "^5.0.8"
+  }
+}

package/templates/test-site/server.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * Test site development server with port management
+ *
+ * Features:
+ * - Uses PortManager for fixed port allocation (3000-3009 range)
+ * - Auto-cleanup of stale processes on restart
+ * - Port reuse for consistent URLs
+ * - Graceful shutdown handling
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync, existsSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Try to load PortManager from parent project
+let PortManager;
+try {
+  // Check if running from installed package
+  const parentPackagePath = join(__dirname, '../../node_modules/.gl-life-claude/utils/port-manager.js');
+  if (existsSync(parentPackagePath)) {
+    const module = await import(parentPackagePath);
+    PortManager = module.PortManager;
+  } else {
+    // Fallback: Check workspace root
+    const workspacePackagePath = join(__dirname, '../../../utils/port-manager.js');
+    if (existsSync(workspacePackagePath)) {
+      const module = await import(workspacePackagePath);
+      PortManager = module.PortManager;
+    }
+  }
+} catch (err) {
+  console.warn('⚠️  Port manager not available, using default port 3000');
+}
+
+/**
+ * Start Vite dev server with port management
+ */
+async function startServer() {
+  let port = 3000;
+  let portManager = null;
+
+  if (PortManager) {
+    try {
+      portManager = new PortManager();
+
+      // Allocate port for test-site
+      const allocation = await portManager.allocate('test-site-dev', {
+        service: 'vite',
+        range: [3000, 3009],
+        autoCleanup: true
+      });
+
+      port = allocation.port;
+      console.log(`✓ Port ${port} allocated for test-site`);
+
+    } catch (err) {
+      console.warn(`⚠️  Port allocation failed: ${err.message}`);
+      console.warn('   Using default port 3000');
+      port = 3000;
+    }
+  }
+
+  // Start Vite server
+  console.log(`🚀 Starting Vite dev server on port ${port}...`);
+
+  const vite = spawn('npx', ['vite', '--port', port.toString(), '--host'], {
+    stdio: 'inherit',
+    shell: true,
+    cwd: __dirname
+  });
+
+  // Graceful shutdown
+  const cleanup = async () => {
+    console.log('\n🛑 Shutting down server...');
+
+    if (vite && !vite.killed) {
+      vite.kill('SIGTERM');
+
+      // Force kill after 5 seconds
+      setTimeout(() => {
+        if (!vite.killed) {
+          vite.kill('SIGKILL');
+        }
+      }, 5000);
+    }
+
+    if (portManager) {
+      try {
+        await portManager.release('test-site-dev');
+        console.log('✓ Port released');
+      } catch (err) {
+        // Ignore release errors on shutdown
+      }
+    }
+
+    process.exit(0);
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  vite.on('error', (err) => {
+    console.error('❌ Server error:', err.message);
+    cleanup();
+  });
+
+  vite.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      console.error(`❌ Server exited with code ${code}`);
+    }
+    cleanup();
+  });
+}
+
+// Run server
+startServer().catch(err => {
+  console.error('❌ Failed to start server:', err.message);
+  process.exit(1);
+});

package/templates/test-site/src/App.css

@@ -0,0 +1,130 @@
+.app {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  min-height: 100vh;
+}
+
+.app-header {
+  margin-bottom: 3rem;
+  text-align: center;
+}
+
+.app-header h1 {
+  font-size: 3em;
+  line-height: 1.1;
+  margin-bottom: 0.5rem;
+}
+
+.app-header p {
+  font-size: 1.2em;
+  color: #888;
+}
+
+.app-main {
+  text-align: left;
+}
+
+.demo-section,
+.instructions,
+.component-list {
+  margin-bottom: 3rem;
+  padding: 2rem;
+  border: 1px solid #ccc;
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.05);
+}
+
+.demo-section h2,
+.instructions h2,
+.component-list h2 {
+  margin-top: 0;
+  font-size: 1.8em;
+}
+
+.demo-description {
+  color: #888;
+  margin-bottom: 2rem;
+  line-height: 1.6;
+}
+
+.component-placeholder {
+  padding: 3rem;
+  border: 2px dashed #646cff;
+  border-radius: 8px;
+  text-align: center;
+  background: rgba(100, 108, 255, 0.05);
+}
+
+.component-placeholder p {
+  font-size: 1.2em;
+  margin-bottom: 1rem;
+  color: #888;
+}
+
+.component-placeholder code {
+  background: rgba(0, 0, 0, 0.2);
+  padding: 0.5rem 1rem;
+  border-radius: 4px;
+  display: inline-block;
+}
+
+.result-display {
+  margin-top: 2rem;
+  padding: 1.5rem;
+  background: rgba(100, 108, 255, 0.1);
+  border-radius: 8px;
+  border-left: 4px solid #646cff;
+}
+
+.result-display h3 {
+  margin: 0 0 1rem 0;
+}
+
+.result-display pre {
+  background: rgba(0, 0, 0, 0.2);
+  padding: 1rem;
+  border-radius: 4px;
+  overflow-x: auto;
+  font-size: 0.9em;
+}
+
+.instructions h3 {
+  margin-top: 2rem;
+  font-size: 1.3em;
+}
+
+.instructions ol {
+  line-height: 2;
+}
+
+.instructions code {
+  background: rgba(255, 255, 255, 0.1);
+  padding: 0.2em 0.4em;
+  border-radius: 4px;
+  font-family: 'Courier New', monospace;
+  font-size: 0.9em;
+}
+
+.code-example {
+  background: rgba(0, 0, 0, 0.3);
+  padding: 1.5rem;
+  border-radius: 8px;
+  overflow-x: auto;
+  font-size: 0.9em;
+  line-height: 1.6;
+  margin-top: 1rem;
+}
+
+.component-list ul {
+  line-height: 2;
+}
+
+.app-footer {
+  margin-top: 4rem;
+  padding-top: 2rem;
+  border-top: 1px solid #ccc;
+  color: #888;
+  font-size: 0.9em;
+  text-align: center;
+}

package/templates/test-site/src/App.jsx

@@ -0,0 +1,78 @@
+import { useState } from 'react'
+import './App.css'
+// Import your components from Agent/src here
+// Example: import { YourComponent } from '../../Agent/src/components/YourComponent'
+
+function App() {
+  return (
+    <div className="app">
+      <header className="app-header">
+        <h1>Integration Test Site</h1>
+        <p>Component Preview for Stakeholder Validation</p>
+      </header>
+
+      <main className="app-main">
+        <section className="demo-section">
+          <h2>Your Components Go Here</h2>
+          <p className="demo-description">
+            Import your UI components from <code>../Agent/src/components/</code> and render them below
+            for stakeholder testing and validation.
+          </p>
+
+          <div className="component-placeholder">
+            <p>👆 Replace this section with your component</p>
+            <code>{'<YourComponent prop1="value" onEvent={handleEvent} />'}</code>
+          </div>
+        </section>
+
+        <section className="instructions">
+          <h2>How to Add Your Components</h2>
+          <ol>
+            <li>Copy your component from <code>Agent/src/components/</code> to <code>test-site/src/components/</code></li>
+            <li>Import it: <code>import &#123; YourComponent &#125; from './components/YourComponent'</code></li>
+            <li>OR import directly: <code>import &#123; YourComponent &#125; from '../../Agent/src/components/YourComponent'</code></li>
+            <li>Render it in the demo section above with realistic props</li>
+            <li>Add event handlers to demonstrate interactivity</li>
+            <li>Run <code>npm run dev</code> to test locally at http://localhost:3000</li>
+            <li>Deploy with <code>npm run deploy</code> to share with stakeholders via GitHub Pages</li>
+          </ol>
+
+          <h3>Example: GitHub Auth Login Component</h3>
+          <pre className="code-example">{`// 1. Copy your login component
+cp ../Agent/src/components/GitHubLogin.jsx src/components/
+
+// 2. Import and use it
+import { GitHubLogin } from './components/GitHubLogin'
+
+function App() {
+  const handleLogin = (user) => {
+    console.log('User logged in:', user)
+  }
+
+  return (
+    <div>
+      <GitHubLogin onLogin={handleLogin} />
+    </div>
+  )
+}`}</pre>
+        </section>
+
+        <section className="component-list">
+          <h2>Quick Start</h2>
+          <ul>
+            <li>📦 Install dependencies: <code>npm install</code></li>
+            <li>🚀 Start dev server: <code>npm run dev</code></li>
+            <li>🌍 Deploy to GitHub Pages: <code>npm run deploy</code></li>
+            <li>📝 Edit <code>src/App.jsx</code> to add your components</li>
+          </ul>
+        </section>
+      </main>
+
+      <footer className="app-footer">
+        <p>Built with Vite + React for fast hot reload</p>
+      </footer>
+    </div>
+  )
+}
+
+export default App

package/templates/test-site/src/index.css

@@ -0,0 +1,39 @@
+:root {
+  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+#root {
+  width: 100%;
+  margin: 0 auto;
+  text-align: center;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+}

package/templates/test-site/src/main.jsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

package/templates/test-site/vite.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 3000,
+    open: true
+  },
+  base: './'
+})