@shaykec/bridge 0.1.0

package/src/server.js

@@ -0,0 +1,497 @@
+/**
+ * ClaudeTeach Bridge Server — WebSocket + SSE + REST communication hub.
+ * Upgraded from packages/core/src/bridge-server.js.
+ *
+ * Endpoints:
+ *   /ws          — WebSocket upgrade (bidirectional)
+ *   /sse         — SSE stream (server-push for canvas-only mode)
+ *   /api/event   — POST, receives user events from canvas
+ *   /api/tier    — GET, returns current tier
+ *   /api/capture — POST, receives web captures
+ *   /api/progress — GET, returns progress data
+ *   /health      — GET, health check
+ *   /            — Serves canvas app static files (if available)
+ *
+ * Usage:
+ *   import { startServer } from '@shaykec/bridge';
+ *   startServer({ port: 3456 });
+ *
+ * Standalone:
+ *   node packages/bridge/src/server.js
+ */
+
+import { createServer } from 'http';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { join, dirname, extname } from 'path';
+import { fileURLToPath } from 'url';
+import { WebSocketServer } from 'ws';
+
+import {
+  PROTOCOL_VERSION,
+  parseEnvelope,
+  createEnvelope,
+  serializeEnvelope,
+  MSG_SYS_CONNECT,
+  MSG_SYS_DISCONNECT,
+  DEFAULT_PORT,
+  INBOX_DIR,
+} from '@shaykec/shared';
+
+import { TierManager, generateClientId, validateHandshake } from './protocol.js';
+import { EventRouter } from './router.js';
+import { renderTemplate, listTemplates } from './templates.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Path to canvas app static files (built by packages/canvas) */
+const CANVAS_DIST = join(__dirname, '..', '..', 'canvas', 'dist');
+
+/** MIME types for static file serving */
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.js':   'application/javascript',
+  '.css':  'text/css',
+  '.json': 'application/json',
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf':  'font/ttf',
+  '.map':  'application/json',
+};
+
+/**
+ * Start the ClaudeTeach bridge server.
+ * @param {object} [options]
+ * @param {number} [options.port=3456] - Port number
+ * @param {function} [options.onReady] - Callback when server is listening
+ * @param {function} [options.onTierChange] - Callback(oldTier, newTier) on tier changes
+ * @param {object} [options.progressProvider] - Object with getProgress() method
+ * @returns {{ server: object, tierManager: TierManager, router: EventRouter, close: function }}
+ */
+export function startServer(options = {}) {
+  const port = options.port || DEFAULT_PORT;
+  const tierManager = new TierManager();
+  const router = new EventRouter(tierManager);
+
+  if (options.onTierChange) {
+    tierManager.onTierChange(options.onTierChange);
+  }
+
+  // Ensure inbox directory exists
+  ensureDir(INBOX_DIR);
+
+  // Create HTTP server
+  const server = createServer((req, res) => {
+    handleRequest(req, res, tierManager, router, options);
+  });
+
+  // Create WebSocket server on the same HTTP server
+  const wss = new WebSocketServer({ server, path: '/ws' });
+
+  wss.on('connection', (ws, req) => {
+    const clientId = generateClientId();
+    let clientType = null;
+    let handshakeComplete = false;
+
+    // Wait for sys:connect handshake
+    const handshakeTimeout = setTimeout(() => {
+      if (!handshakeComplete) {
+        ws.close(4001, 'Handshake timeout');
+      }
+    }, 10000);
+
+    ws.on('message', (rawData) => {
+      const data = rawData.toString();
+
+      if (!handshakeComplete) {
+        // First message must be sys:connect
+        const { valid, envelope, error } = parseEnvelope(data);
+        if (!valid || envelope.type !== MSG_SYS_CONNECT) {
+          ws.close(4002, 'First message must be sys:connect');
+          clearTimeout(handshakeTimeout);
+          return;
+        }
+
+        const validation = validateHandshake(envelope.payload);
+        if (!validation.valid) {
+          ws.close(4003, validation.error);
+          clearTimeout(handshakeTimeout);
+          return;
+        }
+
+        clientType = envelope.payload.clientType;
+        handshakeComplete = true;
+        clearTimeout(handshakeTimeout);
+
+        tierManager.addWsClient(clientId, ws, clientType);
+
+        // Send connect acknowledgment
+        ws.send(serializeEnvelope(MSG_SYS_CONNECT, {
+          clientId,
+          serverVersion: PROTOCOL_VERSION,
+          tier: tierManager.getTier(),
+        }, 'bridge'));
+
+        return;
+      }
+
+      // After handshake, route messages through the router
+      const result = router.handleWsMessage(data, clientId);
+      if (!result.handled && result.error) {
+        ws.send(JSON.stringify({ error: result.error }));
+      }
+    });
+
+    ws.on('close', () => {
+      clearTimeout(handshakeTimeout);
+      if (clientType) {
+        tierManager.removeWsClient(clientId);
+      }
+    });
+
+    ws.on('error', () => {
+      clearTimeout(handshakeTimeout);
+      if (clientType) {
+        tierManager.removeWsClient(clientId);
+      }
+    });
+  });
+
+  // Start heartbeat
+  tierManager.startHeartbeat();
+
+  // Start listening
+  server.listen(port, () => {
+    console.log(`ClaudeTeach bridge server running on http://localhost:${port}`);
+    console.log(`  WebSocket  /ws          — bidirectional (extension + canvas)`);
+    console.log(`  SSE        /sse         — server-push (canvas-only)`);
+    console.log(`  POST       /api/event   — receive user events`);
+    console.log(`  GET        /api/tier    — current tier info`);
+    console.log(`  POST       /api/capture — receive web captures`);
+    console.log(`  GET        /api/progress — progress data`);
+    console.log(`  GET        /health      — health check`);
+    if (existsSync(CANVAS_DIST)) {
+      console.log(`  Static     /            — canvas app from ${CANVAS_DIST}`);
+    }
+    console.log(`\nPress Ctrl+C to stop.`);
+
+    if (options.onReady) {
+      options.onReady({ port, tierManager, router });
+    }
+  });
+
+  const close = () => {
+    tierManager.stopHeartbeat();
+    wss.close();
+    server.close();
+  };
+
+  return { server, wss, tierManager, router, close };
+}
+
+/**
+ * Handle HTTP requests.
+ */
+function handleRequest(req, res, tierManager, router, options) {
+  // CORS headers
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  const pathname = url.pathname;
+
+  // --- SSE endpoint ---
+  if (req.method === 'GET' && pathname === '/sse') {
+    handleSse(req, res, tierManager);
+    return;
+  }
+
+  // --- REST API endpoints ---
+  if (req.method === 'POST' && pathname === '/api/event') {
+    handleApiEvent(req, res, router);
+    return;
+  }
+
+  if (req.method === 'GET' && pathname === '/api/tier') {
+    handleApiTier(res, tierManager);
+    return;
+  }
+
+  if (req.method === 'POST' && pathname === '/api/capture') {
+    handleApiCapture(req, res);
+    return;
+  }
+
+  if (req.method === 'GET' && pathname === '/api/progress') {
+    handleApiProgress(res, options);
+    return;
+  }
+
+  if (req.method === 'GET' && pathname === '/api/events') {
+    handleApiPollEvents(res, router);
+    return;
+  }
+
+  if (req.method === 'GET' && pathname === '/api/templates') {
+    handleApiTemplates(res);
+    return;
+  }
+
+  if (req.method === 'POST' && pathname === '/api/visual') {
+    handleApiVisual(req, res, router);
+    return;
+  }
+
+  // --- Health check ---
+  if (req.method === 'GET' && pathname === '/health') {
+    sendJson(res, 200, {
+      status: 'ok',
+      version: '0.1.0',
+      tier: tierManager.getTierInfo(),
+      uptime: process.uptime(),
+    });
+    return;
+  }
+
+  // --- Static file serving (canvas app) ---
+  if (req.method === 'GET') {
+    if (serveStatic(res, pathname)) return;
+  }
+
+  // 404
+  res.writeHead(404, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: 'Not found' }));
+}
+
+/**
+ * Handle SSE connections.
+ */
+function handleSse(req, res, tierManager) {
+  const clientId = generateClientId();
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'Access-Control-Allow-Origin': '*',
+  });
+
+  // Send initial connection event
+  const connectMsg = JSON.stringify(createEnvelope(MSG_SYS_CONNECT, {
+    clientId,
+    serverVersion: PROTOCOL_VERSION,
+    tier: tierManager.getTier(),
+  }, 'bridge'));
+  res.write(`data: ${connectMsg}\n\n`);
+
+  // Register as canvas SSE client
+  tierManager.addSseClient(clientId, res, 'canvas');
+
+  // Handle disconnect
+  req.on('close', () => {
+    tierManager.removeSseClient(clientId);
+  });
+
+  req.on('error', () => {
+    tierManager.removeSseClient(clientId);
+  });
+}
+
+/**
+ * POST /api/event — receive user events from canvas.
+ */
+function handleApiEvent(req, res, router) {
+  readBody(req, (err, body) => {
+    if (err) {
+      sendJson(res, 400, { error: 'Invalid request body' });
+      return;
+    }
+    const result = router.handleRestEvent(body);
+    if (result.ok) {
+      sendJson(res, 200, { ok: true });
+    } else {
+      sendJson(res, 400, { error: result.error });
+    }
+  });
+}
+
+/**
+ * GET /api/tier — return current tier info.
+ */
+function handleApiTier(res, tierManager) {
+  sendJson(res, 200, tierManager.getTierInfo());
+}
+
+/**
+ * POST /api/capture — receive web captures, write to .teach/inbox/.
+ */
+function handleApiCapture(req, res) {
+  readBody(req, (err, data) => {
+    if (err) {
+      sendJson(res, 400, { error: 'Invalid request body' });
+      return;
+    }
+
+    try {
+      ensureDir(INBOX_DIR);
+      const title = data.title || data.pageTitle || 'untitled';
+      const filename = `${Date.now()}-${slugify(title)}.json`;
+      const filePath = join(INBOX_DIR, filename);
+      writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+      sendJson(res, 200, { ok: true, saved: filename });
+    } catch (writeErr) {
+      sendJson(res, 500, { error: writeErr.message });
+    }
+  });
+}
+
+/**
+ * GET /api/progress — return progress data.
+ */
+function handleApiProgress(res, options) {
+  if (options.progressProvider && typeof options.progressProvider.getProgress === 'function') {
+    const progress = options.progressProvider.getProgress();
+    sendJson(res, 200, progress);
+  } else {
+    sendJson(res, 200, { user: { xp: 0 }, modules: {} });
+  }
+}
+
+/**
+ * GET /api/events — poll queued user events.
+ */
+function handleApiPollEvents(res, router) {
+  const events = router.pollEvents();
+  sendJson(res, 200, { events, count: events.length });
+}
+
+/**
+ * GET /api/templates — list available templates.
+ */
+function handleApiTemplates(res) {
+  sendJson(res, 200, { templates: listTemplates() });
+}
+
+/**
+ * POST /api/visual — push a visual command to connected clients.
+ * Used by the plugin to send canvas:* commands.
+ */
+function handleApiVisual(req, res, router) {
+  readBody(req, (err, body) => {
+    if (err) {
+      sendJson(res, 400, { error: 'Invalid request body' });
+      return;
+    }
+
+    const { valid, envelope, error } = parseEnvelope(body);
+    if (!valid) {
+      sendJson(res, 400, { error });
+      return;
+    }
+
+    // Check if we should render a template
+    if (envelope.payload && envelope.payload.template) {
+      const rendered = renderTemplate(envelope.payload.template, envelope.payload.data || {});
+      if (rendered) {
+        envelope.payload.renderedHtml = rendered;
+      }
+    }
+
+    router.routeVisualCommand(envelope);
+    sendJson(res, 200, { ok: true, tier: router.tierManager.getTier() });
+  });
+}
+
+/**
+ * Serve static files from the canvas dist directory.
+ * @param {object} res
+ * @param {string} pathname
+ * @returns {boolean} true if file was served
+ */
+function serveStatic(res, pathname) {
+  if (!existsSync(CANVAS_DIST)) return false;
+
+  // Map / to /index.html
+  let filePath = join(CANVAS_DIST, pathname === '/' ? 'index.html' : pathname);
+
+  // Security: prevent directory traversal
+  if (!filePath.startsWith(CANVAS_DIST)) {
+    return false;
+  }
+
+  if (!existsSync(filePath)) {
+    // SPA fallback: serve index.html for non-file paths
+    const indexPath = join(CANVAS_DIST, 'index.html');
+    if (existsSync(indexPath) && !extname(pathname)) {
+      filePath = indexPath;
+    } else {
+      return false;
+    }
+  }
+
+  try {
+    const stat = statSync(filePath);
+    if (stat.isDirectory()) {
+      filePath = join(filePath, 'index.html');
+      if (!existsSync(filePath)) return false;
+    }
+
+    const ext = extname(filePath);
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+    const content = readFileSync(filePath);
+    res.writeHead(200, { 'Content-Type': contentType });
+    res.end(content);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- Helpers ---
+
+function readBody(req, callback) {
+  let body = '';
+  req.on('data', chunk => { body += chunk; });
+  req.on('end', () => {
+    try {
+      callback(null, JSON.parse(body));
+    } catch {
+      callback(new Error('Invalid JSON'));
+    }
+  });
+  req.on('error', (err) => {
+    callback(err);
+  });
+}
+
+function sendJson(res, status, data) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 50);
+}
+
+function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+// --- Standalone execution ---
+if (process.argv[1] && process.argv[1].includes('bridge/src/server.js')) {
+  const port = parseInt(process.env.PORT || process.argv[2] || DEFAULT_PORT, 10);
+  startServer({ port });
+}

package/src/templates.js

@@ -0,0 +1,155 @@
+/**
+ * Template engine for ClaudeTeach bridge server.
+ * Loads HTML templates from the templates/ directory and fills
+ * placeholder slots with data from visual command payloads.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+
+/** In-memory template cache */
+const templateCache = new Map();
+
+/**
+ * Load a template by name. Cached after first read.
+ * @param {string} name - Template filename (without or with .html extension)
+ * @returns {string|null} Template HTML or null if not found
+ */
+export function loadTemplate(name) {
+  const filename = name.endsWith('.html') ? name : `${name}.html`;
+
+  if (templateCache.has(filename)) {
+    return templateCache.get(filename);
+  }
+
+  const filePath = join(TEMPLATES_DIR, filename);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  const content = readFileSync(filePath, 'utf-8');
+  templateCache.set(filename, content);
+  return content;
+}
+
+/**
+ * Render a template with data. Replaces {{key}} placeholders with values.
+ * Supports nested keys via dot notation: {{progress.xp}}.
+ * Also supports {{#items}}...{{/items}} for array iteration (simple blocks).
+ * @param {string} templateName - Template name
+ * @param {object} data - Data to fill placeholders
+ * @returns {string|null} Rendered HTML or null if template not found
+ */
+export function renderTemplate(templateName, data) {
+  const template = loadTemplate(templateName);
+  if (!template) return null;
+
+  return fillTemplate(template, data);
+}
+
+/**
+ * Fill a template string with data.
+ * @param {string} template - Template HTML string
+ * @param {object} data - Data object
+ * @returns {string} Rendered HTML
+ */
+export function fillTemplate(template, data) {
+  let result = template;
+
+  // Handle array blocks: {{#items}}...{{/items}}
+  result = result.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (match, key, block) => {
+    const arr = resolveValue(data, key);
+    if (!Array.isArray(arr)) return '';
+
+    return arr.map((item, index) => {
+      // Within a block, {{.}} refers to the item itself (for primitives)
+      // {{.property}} refers to a property of the item (for objects)
+      let rendered = block;
+
+      if (typeof item === 'object' && item !== null) {
+        // Replace {{.key}} with item properties
+        rendered = rendered.replace(/\{\{\.(\w+)\}\}/g, (_, prop) => {
+          return escapeHtml(String(item[prop] ?? ''));
+        });
+        // Replace {{.}} with JSON of the object
+        rendered = rendered.replace(/\{\{\.\}\}/g, escapeHtml(JSON.stringify(item)));
+      } else {
+        // Primitive — replace {{.}} with the value
+        rendered = rendered.replace(/\{\{\.\}\}/g, escapeHtml(String(item)));
+      }
+
+      // Replace {{@index}} with the iteration index
+      rendered = rendered.replace(/\{\{@index\}\}/g, String(index));
+
+      return rendered;
+    }).join('');
+  });
+
+  // Handle JSON injection: {{{json:key}}} (triple braces = unescaped JSON)
+  result = result.replace(/\{\{\{json:([^}]+)\}\}\}/g, (_, key) => {
+    const value = resolveValue(data, key.trim());
+    return JSON.stringify(value ?? null);
+  });
+
+  // Handle simple placeholders: {{key}} and {{key.nested}}
+  result = result.replace(/\{\{([^#/][^}]*)\}\}/g, (match, key) => {
+    const value = resolveValue(data, key.trim());
+    if (value === undefined || value === null) return '';
+    return escapeHtml(String(value));
+  });
+
+  return result;
+}
+
+/**
+ * Resolve a dot-notation key against a data object.
+ * @param {object} data
+ * @param {string} key - e.g. 'progress.xp' or 'question'
+ * @returns {*}
+ */
+function resolveValue(data, key) {
+  const parts = key.split('.');
+  let current = data;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Escape HTML special characters.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * List available templates.
+ * @returns {string[]} Array of template names (without .html extension)
+ */
+export function listTemplates() {
+  if (!existsSync(TEMPLATES_DIR)) return [];
+  return readdirSync(TEMPLATES_DIR)
+    .filter(f => f.endsWith('.html'))
+    .map(f => f.replace(/\.html$/, ''));
+}
+
+/**
+ * Clear the template cache (useful for development).
+ */
+export function clearTemplateCache() {
+  templateCache.clear();
+}