@rashidee/co2 1.2.5

package/plugin/skills/mockgen-tailwind/references/mockup-hub-template.md

@@ -0,0 +1,498 @@
+# Mockup Hub — Single Node Server for ALL Application Mockups
+
+The Mockup Hub is ONE zero-dependency Node.js application at `<root>/mockup/` that serves
+the mockups of EVERY application in the project. Per-application mockup folders
+(`<app_folder>/context/mockup/`) contain ONLY assets (HTML/CSS/JS/images + a manifest) —
+they contain NO server of their own.
+
+- **Tailwind mockups** (`mockgen-tailwind`): the hub assembles shell + header + sidebar +
+  content + footer server-side at `/{app_slug}/{role}/{page}`.
+- **shadcn mockups** (`mockgen-shadcn`): the hub serves the app's built `dist/` folder at
+  `/{app_slug}/...` with SPA fallback to `dist/index.html`.
+- **Landing page** at `/`: dynamically lists ALL applications and their roles. Roles are
+  clickable only when the app's mockup is ready; otherwise they render as disabled
+  (grayed, no `href`) chips with a status hint ("Mockups not generated yet" /
+  "Build required").
+- **Port** is configurable: `PORT` env var → `mockup.config.json` `port` → default `3000`.
+
+The hub has **zero npm dependencies** — `npm start` (or `node server.js`) works with no
+`npm install`.
+
+## File Structure
+
+```
+<root>/
+  mockup/                     # ← the hub (this template)
+    server.js                 # zero-dependency Node HTTP server
+    package.json              # no dependencies; "start": "node server.js"
+    mockup.config.json        # { "port": 3000 } — user-editable
+    .gitignore
+  1_first_app/
+    context/mockup/           # assets only (+ mockup-manifest.json)
+  2_second_app/
+    context/mockup/
+```
+
+## Ensure-Hub Rules (run by every mockgen-* execution, including module-filtered runs)
+
+1. If `<root>/mockup/server.js` does NOT exist: create ALL four hub files from the
+   templates below.
+2. If it exists: read the `HUB_VERSION` constant in the existing `server.js`.
+   - Existing version **< template version** → overwrite `server.js` and `package.json`
+     with the templates (upgrade).
+   - Existing version **>= template version**, or no marker found (user-customized) →
+     leave `server.js` and `package.json` untouched.
+3. `mockup.config.json`: create ONLY if missing. NEVER overwrite an existing one — it
+   holds the user's port choice. It is per-machine and gitignored.
+4. `.gitignore`: create ONLY if missing.
+5. Never place per-application assets inside `<root>/mockup/`. Conversely, everything the
+   hub generates or needs (config, logs, any `node_modules/`) stays inside `<root>/mockup/`
+   and is covered by its `.gitignore`.
+
+## mockup-manifest.json Schema (written to `<app_folder>/context/mockup/`)
+
+Every mockgen-* run writes/updates this file. The hub uses it for discovery, routing and
+the landing page.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `app` | string | App slug used in URLs = app folder name minus leading `<number>_` (e.g. `hub_middleware`) |
+| `appName` | string | Display name (e.g. "Hub Middleware") |
+| `description` | string | Short app description from PRD.md |
+| `stack` | string | `"tailwind"` or `"shadcn"` |
+| `version` | string | Target version the mockups were generated for (e.g. `v1.0.3`) |
+| `generatedAt` | string | ISO date of the last generation |
+| `roles` | array | One entry per role: `{ "name", "slug", "screens" }`. `slug` uses the stack's convention — snake_case (tailwind) or kebab-case (shadcn). `screens` = number of screens generated for the role |
+| `reports` | array (optional) | Report layout file names, if any |
+
+Example:
+
+```json
+{
+  "app": "hub_middleware",
+  "appName": "Hub Middleware",
+  "description": "Central middleware for labour mobility data exchange.",
+  "stack": "tailwind",
+  "version": "v1.0.3",
+  "generatedAt": "2026-07-12",
+  "roles": [
+    { "name": "Hub Administrator", "slug": "hub_administrator", "screens": 12 },
+    { "name": "Hub Operation Support", "slug": "hub_operation_support", "screens": 9 }
+  ],
+  "reports": ["staff_allocation_summary.html"]
+}
+```
+
+## server.js Template
+
+```javascript
+#!/usr/bin/env node
+/*
+ * CO2 Mockup Hub — one server for ALL application mockups.
+ * HUB_VERSION: 1   (marker used by mockgen-* skills to decide upgrades — do not remove)
+ *
+ * Discovers every root-level application folder containing context/PRD.md.
+ * Apps with a context/mockup/mockup-manifest.json are routable:
+ *   - stack "tailwind": pages assembled from partials + content fragments
+ *   - stack "shadcn":  served from the built dist/ folder (SPA fallback)
+ * Port: PORT env var > mockup.config.json "port" > 3000.
+ */
+'use strict';
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const HUB_VERSION = 1;
+const HUB_DIR = __dirname;
+const ROOT_DIR = path.resolve(HUB_DIR, '..');
+const SAFE_SEG = /^[A-Za-z0-9._-]+$/;
+
+function resolvePort() {
+  const envPort = parseInt(process.env.PORT || '', 10);
+  if (Number.isInteger(envPort) && envPort > 0) return envPort;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(HUB_DIR, 'mockup.config.json'), 'utf8'));
+    const cfgPort = parseInt(cfg.port, 10);
+    if (Number.isInteger(cfgPort) && cfgPort > 0) return cfgPort;
+  } catch (err) { /* missing/invalid config — use default */ }
+  return 3000;
+}
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.map': 'application/json',
+  '.txt': 'text/plain; charset=utf-8',
+  '.pdf': 'application/pdf',
+};
+
+// ── Discovery ────────────────────────────────────────────────────────────────
+
+function titleCase(slug) {
+  return slug.replace(/[_-]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function rolesFromPrd(appDir) {
+  try {
+    const prd = fs.readFileSync(path.join(appDir, 'context', 'PRD.md'), 'utf8');
+    const names = new Set();
+    for (const line of prd.split('\n')) {
+      if (line.includes('~~')) continue; // skip strikethrough (deprecated) items
+      const m = line.match(/As an? (.+?) user/);
+      if (m) names.add(m[1].trim());
+    }
+    return Array.from(names).map((name) => ({ name, slug: null, screens: 0 }));
+  } catch (err) {
+    return [];
+  }
+}
+
+function discoverApps() {
+  let entries;
+  try { entries = fs.readdirSync(ROOT_DIR, { withFileTypes: true }); } catch (err) { return []; }
+  const apps = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const appDir = path.join(ROOT_DIR, entry.name);
+    if (!fs.existsSync(path.join(appDir, 'context', 'PRD.md'))) continue;
+    const slug = entry.name.replace(/^\d+_/, '');
+    const mockupDir = path.join(appDir, 'context', 'mockup');
+    let manifest = null;
+    try {
+      manifest = JSON.parse(fs.readFileSync(path.join(mockupDir, 'mockup-manifest.json'), 'utf8'));
+    } catch (err) { /* mockups not generated yet */ }
+    let status = 'not-generated';
+    if (manifest && manifest.stack === 'shadcn') {
+      status = fs.existsSync(path.join(mockupDir, 'dist', 'index.html')) ? 'ready' : 'build-required';
+    } else if (manifest) {
+      status = fs.existsSync(path.join(mockupDir, 'partials', 'shell.html')) ? 'ready' : 'not-generated';
+    }
+    apps.push({
+      slug,
+      folder: entry.name,
+      appName: (manifest && manifest.appName) || titleCase(slug),
+      description: (manifest && manifest.description) || '',
+      version: (manifest && manifest.version) || '',
+      stack: manifest ? manifest.stack : null,
+      status,
+      mockupDir,
+      roles: manifest ? (manifest.roles || []) : rolesFromPrd(appDir),
+    });
+  }
+  return apps.sort((a, b) => a.folder.localeCompare(b.folder));
+}
+
+function findApp(slug) {
+  return discoverApps().find((a) => a.slug === slug) || null;
+}
+
+// ── Response helpers ─────────────────────────────────────────────────────────
+
+function send(res, code, body, type) {
+  res.writeHead(code, { 'Content-Type': type || 'text/html; charset=utf-8' });
+  res.end(body);
+}
+
+function redirect(res, location) {
+  res.writeHead(302, { Location: location });
+  res.end();
+}
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function safeJoin(baseDir, segments) {
+  if (!segments.every((s) => SAFE_SEG.test(s))) return null;
+  const target = path.normalize(path.join(baseDir, segments.join(path.sep)));
+  if (target !== baseDir && !target.startsWith(baseDir + path.sep)) return null;
+  return target;
+}
+
+function serveFile(res, filePath) {
+  if (!filePath) return false;
+  let stat;
+  try { stat = fs.statSync(filePath); } catch (err) { return false; }
+  if (!stat.isFile()) return false;
+  const type = MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+  send(res, 200, fs.readFileSync(filePath), type);
+  return true;
+}
+
+function readText(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch (err) { return null; }
+}
+
+// ── Landing page ─────────────────────────────────────────────────────────────
+
+const LANDING_CSS = `
+  * { box-sizing: border-box; margin: 0; }
+  body { font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+         background: #f1f5f9; color: #0f172a; padding: 40px 20px; }
+  .wrap { max-width: 960px; margin: 0 auto; }
+  h1 { font-size: 26px; margin-bottom: 4px; }
+  .sub { color: #64748b; font-size: 14px; margin-bottom: 28px; }
+  .card { background: #fff; border: 1px solid #e2e8f0; border-radius: 12px;
+          padding: 20px; margin-bottom: 16px; }
+  .card h2 { font-size: 18px; display: inline; }
+  .meta { color: #94a3b8; font-size: 12px; margin-left: 8px; }
+  .badge { display: inline-block; font-size: 11px; padding: 2px 8px; border-radius: 999px;
+           margin-left: 8px; vertical-align: 2px; }
+  .badge.ready { background: #dcfce7; color: #166534; }
+  .badge.pending { background: #fef3c7; color: #92400e; }
+  .hint { color: #94a3b8; font-size: 12px; margin-top: 10px; }
+  .hint code { background: #f1f5f9; padding: 1px 5px; border-radius: 4px; }
+  .roles { margin-top: 12px; display: flex; flex-wrap: wrap; gap: 8px; }
+  .role { display: inline-block; font-size: 13px; padding: 6px 14px; border-radius: 8px;
+          border: 1px solid #cbd5e1; text-decoration: none; color: #0f172a; }
+  a.role:hover { border-color: #2563eb; color: #2563eb; }
+  .role.disabled { color: #cbd5e1; border-color: #e2e8f0; cursor: not-allowed; }
+  .index-link { font-size: 12px; margin-left: 8px; }
+  .foot { color: #94a3b8; font-size: 12px; text-align: center; margin-top: 28px; }
+`;
+
+function renderRoleChips(app) {
+  if (!app.roles.length) {
+    return '<span class="role disabled">No roles found</span>';
+  }
+  return app.roles.map((role) => {
+    if (app.status === 'ready' && role.slug) {
+      return '<a class="role" href="/' + app.slug + '/' + role.slug + '/home">'
+        + escapeHtml(role.name) + ' &rarr;</a>';
+    }
+    return '<span class="role disabled" aria-disabled="true">' + escapeHtml(role.name) + '</span>';
+  }).join('\n      ');
+}
+
+function renderAppCard(app) {
+  const badge = app.status === 'ready'
+    ? '<span class="badge ready">Ready' + (app.stack ? ' · ' + escapeHtml(app.stack) : '') + '</span>'
+    : (app.status === 'build-required'
+      ? '<span class="badge pending">Build required</span>'
+      : '<span class="badge pending">Not generated yet</span>');
+  const indexLink = app.status === 'ready'
+    ? '<a class="index-link" href="/' + app.slug + '">screen index</a>' : '';
+  let hint = '';
+  if (app.status === 'build-required') {
+    hint = '<p class="hint">Run <code>cd ' + escapeHtml(app.folder)
+      + '/context/mockup &amp;&amp; npm install &amp;&amp; npm run build</code> to make this app viewable.</p>';
+  } else if (app.status === 'not-generated') {
+    hint = '<p class="hint">Run a <code>mockgen-*</code> skill for this application to generate its mockups.</p>';
+  }
+  return '<div class="card">\n'
+    + '  <h2>' + escapeHtml(app.appName) + '</h2>'
+    + (app.version ? '<span class="meta">' + escapeHtml(app.version) + '</span>' : '')
+    + badge + indexLink + '\n'
+    + (app.description ? '  <p class="sub" style="margin:6px 0 0">' + escapeHtml(app.description) + '</p>\n' : '')
+    + '  <div class="roles">\n      ' + renderRoleChips(app) + '\n  </div>\n'
+    + hint + '\n</div>';
+}
+
+function renderLanding(apps) {
+  return '<!DOCTYPE html>\n<html lang="en">\n<head>\n<meta charset="UTF-8">\n'
+    + '<meta name="viewport" content="width=device-width, initial-scale=1.0">\n'
+    + '<title>Mockup Hub</title>\n<style>' + LANDING_CSS + '</style>\n</head>\n<body>\n'
+    + '<div class="wrap">\n<h1>Mockup Hub</h1>\n'
+    + '<p class="sub">All application mockups, served from one place. '
+    + apps.length + ' application(s) discovered. Click a role to open its dashboard.</p>\n'
+    + apps.map(renderAppCard).join('\n')
+    + '\n<p class="foot">CO2 Mockup Hub v' + HUB_VERSION
+    + ' &middot; port via PORT env or mockup.config.json</p>\n</div>\n</body>\n</html>';
+}
+
+function notReadyPage(app) {
+  return renderLanding([app]);
+}
+
+function notFoundPage(what) {
+  return '<!DOCTYPE html><html><body style="font-family:sans-serif;padding:40px">'
+    + '<h1>404 — Not found' + (what ? ': ' + escapeHtml(what) : '') + '</h1>'
+    + '<p><a href="/">Back to Mockup Hub</a></p></body></html>';
+}
+
+// ── Tailwind assembly ────────────────────────────────────────────────────────
+
+function assemblePage(app, role, page) {
+  const dir = app.mockupDir;
+  const shell = readText(path.join(dir, 'partials', 'shell.html'));
+  let header = readText(path.join(dir, 'partials', 'header.html'));
+  const sidebar = readText(path.join(dir, 'partials', 'sidebar-' + role + '.html'));
+  const footer = readText(path.join(dir, 'partials', 'footer.html'));
+  const content = readText(path.join(dir, role, 'content', page + '.html'));
+  if (!shell || !header || !sidebar || !footer) return null;
+  header = header.replace(/\{\{ROLE\}\}/g, role).replace(/\{\{APP_SLUG\}\}/g, app.slug);
+  const body = content
+    || '<div class="p-6 text-red-500">Page not found: ' + escapeHtml(page) + '</div>';
+  return shell
+    .replace('{{HEADER}}', header)
+    .replace('{{SIDEBAR}}', sidebar.replace(/\{\{APP_SLUG\}\}/g, app.slug))
+    .replace('{{CONTENT}}', body)
+    .replace('{{FOOTER}}', footer);
+}
+
+// ── Routing ──────────────────────────────────────────────────────────────────
+
+function routeTailwind(app, segs, res) {
+  if (segs.length === 1) {
+    if (serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) return;
+    const first = app.roles.find((r) => r.slug);
+    if (first) return redirect(res, '/' + app.slug + '/' + first.slug + '/home');
+    return send(res, 404, notFoundPage(app.slug));
+  }
+  if (segs[1] === 'static' || segs[1] === 'reports') {
+    const file = safeJoin(path.join(app.mockupDir, segs[1]), segs.slice(2));
+    if (serveFile(res, file)) return;
+    return send(res, 404, notFoundPage());
+  }
+  if (!SAFE_SEG.test(segs[1])) return send(res, 400, notFoundPage());
+  if (segs.length === 2) return redirect(res, '/' + app.slug + '/' + segs[1] + '/home');
+  if (segs.length === 3 && SAFE_SEG.test(segs[2])) {
+    const html = assemblePage(app, segs[1], segs[2]);
+    if (html === null) {
+      return send(res, 500, '<h1>Missing partials. Re-run the mockup generator.</h1>');
+    }
+    return send(res, 200, html);
+  }
+  return send(res, 404, notFoundPage());
+}
+
+function routeShadcn(app, segs, res) {
+  if (segs.length === 1 && serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) return;
+  if (segs[1] === 'reports') {
+    const file = safeJoin(path.join(app.mockupDir, 'public', 'reports'), segs.slice(2));
+    if (serveFile(res, file)) return;
+    return send(res, 404, notFoundPage());
+  }
+  const distDir = path.join(app.mockupDir, 'dist');
+  if (segs.length > 1) {
+    const file = safeJoin(distDir, segs.slice(1));
+    if (serveFile(res, file)) return;
+  }
+  // SPA fallback — React Router (basename /{app_slug}) handles the path client-side
+  if (serveFile(res, path.join(distDir, 'index.html'))) return;
+  return send(res, 404, notFoundPage(app.slug));
+}
+
+function route(req, res) {
+  const urlPath = decodeURIComponent((req.url || '/').split('?')[0]);
+  const segs = urlPath.split('/').filter(Boolean);
+
+  if (segs.length === 0) return send(res, 200, renderLanding(discoverApps()));
+  if (urlPath === '/favicon.ico') { res.writeHead(204); return res.end(); }
+
+  // HTMX fragment endpoint (tailwind): /api/content/:app/:role/:page
+  if (segs[0] === 'api' && segs[1] === 'content') {
+    if (segs.length !== 5) return send(res, 404, notFoundPage());
+    const app = findApp(segs[2]);
+    if (!app || app.status !== 'ready' || app.stack !== 'tailwind') {
+      return send(res, 404, notFoundPage(segs[2]));
+    }
+    if (!SAFE_SEG.test(segs[3]) || !SAFE_SEG.test(segs[4])) return send(res, 400, notFoundPage());
+    const content = readText(path.join(app.mockupDir, segs[3], 'content', segs[4] + '.html'));
+    if (content === null) {
+      return send(res, 404, '<div class="p-6 text-red-500">Content not found.</div>');
+    }
+    return send(res, 200, content);
+  }
+
+  if (!SAFE_SEG.test(segs[0])) return send(res, 400, notFoundPage());
+  const app = findApp(segs[0]);
+  if (!app) return send(res, 404, notFoundPage(segs[0]));
+  if (app.status !== 'ready') return send(res, 200, notReadyPage(app));
+
+  if (app.stack === 'shadcn') return routeShadcn(app, segs, res);
+  return routeTailwind(app, segs, res);
+}
+
+// ── Start ────────────────────────────────────────────────────────────────────
+
+const PORT = resolvePort();
+const server = http.createServer((req, res) => {
+  try {
+    route(req, res);
+  } catch (err) {
+    send(res, 500, '<h1>500 — Hub error</h1><pre>' + escapeHtml(err && err.stack || err) + '</pre>');
+  }
+});
+
+server.listen(PORT, () => {
+  console.log('');
+  console.log('  CO2 Mockup Hub v' + HUB_VERSION + ' running at:');
+  console.log('  -> http://localhost:' + PORT);
+  console.log('');
+  console.log('  Serving mockups for all applications under: ' + ROOT_DIR);
+  console.log('  Change port: PORT env var, or "port" in mockup.config.json');
+  console.log('');
+});
+```
+
+## package.json Template
+
+```json
+{
+  "name": "co2-mockup-hub",
+  "private": true,
+  "version": "1.0.0",
+  "description": "CO2 Mockup Hub — single server for all application mockups",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js"
+  }
+}
+```
+
+## mockup.config.json Template
+
+Create only if missing — never overwrite (it stores the user's port choice).
+
+```json
+{
+  "port": 3000
+}
+```
+
+Port precedence at startup: `PORT` env var (e.g. `PORT=4000 npm start`) →
+`mockup.config.json` `port` → `3000`.
+
+## .gitignore Template
+
+Everything npm- or machine-generated inside `<root>/mockup/` stays inside `<root>/mockup/`
+and is gitignored there. The hub has zero dependencies, so `node_modules/` normally never
+exists — the rule is a safety net in case a user installs packages. `mockup.config.json`
+is per-machine (each machine keeps its own port choice; the skills recreate it if missing),
+so it is gitignored too.
+
+```
+node_modules/
+package-lock.json
+mockup.config.json
+.DS_Store
+*.log
+```
+
+## Quick Start (for output summaries)
+
+```
+Mockup Hub
+==========
+1. cd <root>/mockup
+2. npm start          (zero dependencies — no npm install required)
+3. Open http://localhost:3000 in your browser
+   (change port: PORT=4000 npm start, or edit mockup.config.json)
+```