@fias/plugin-dev-harness 1.1.0

package/dist/server/static/harness.js

@@ -0,0 +1,345 @@
+/**
+ * FIAS Dev Harness — Client-side Bridge Host
+ *
+ * Ported from the production PluginBridgeHost
+ * (client/src/arche/components/PluginBridge.ts).
+ *
+ * Handles postMessage communication with the plugin iframe,
+ * enforcing permissions and rate limits, and proxying server-side
+ * operations through the harness Express server.
+ */
+(function () {
+  'use strict';
+
+  var iframe = document.getElementById('plugin-iframe');
+  var consoleBody = document.getElementById('console-body');
+  var consoleCount = document.getElementById('console-count');
+  var consoleToggle = document.getElementById('console-toggle');
+  var creditBalance = document.getElementById('credit-balance');
+  var themeToggle = document.getElementById('theme-toggle');
+  var reloadBtn = document.getElementById('reload-btn');
+  var modeBadge = document.getElementById('mode-badge');
+  var permissionsEl = document.getElementById('permissions');
+
+  var messageCount = 0;
+  var currentTheme = 'dark';
+  var cachedConfig = null;
+
+  /** Permission requirements per bridge call type (matches production) */
+  var PERMISSION_MAP = {
+    get_user: 'user:profile:read',
+    get_theme: 'theme:read',
+    entity_invoke: 'entities:invoke',
+    storage_read: 'storage:sandbox',
+    storage_write: 'storage:sandbox',
+    storage_list: 'storage:sandbox',
+    storage_delete: 'storage:sandbox',
+  };
+
+  /** Rate limits per message type (matches production) */
+  var RATE_LIMITS = {
+    entity_invoke: { maxPerMinute: 60 },
+    storage_write: { maxPerMinute: 120 },
+    storage_read: { maxPerMinute: 300 },
+    storage_list: { maxPerMinute: 60 },
+    storage_delete: { maxPerMinute: 60 },
+  };
+  var rateBuckets = {};
+
+  // ────────────────────────────────────────────────────────────────
+  // Initialization
+  // ────────────────────────────────────────────────────────────────
+
+  fetchConfig().then(function (config) {
+    cachedConfig = config;
+    currentTheme = config.mockTheme || 'dark';
+
+    // Update UI
+    modeBadge.textContent = config.isLive ? 'LIVE' : 'MOCK';
+    modeBadge.className = 'mode-badge ' + (config.isLive ? 'mode-live' : 'mode-mock');
+
+    permissionsEl.innerHTML = config.permissions
+      .map(function (p) {
+        return '<span class="perm-badge">' + escapeHtml(p) + '</span>';
+      })
+      .join('');
+
+    if (config.isLive) {
+      creditBalance.style.display = 'inline';
+      fetchCredits();
+    }
+
+    // Load plugin
+    iframe.src = config.pluginUrl;
+  });
+
+  // ────────────────────────────────────────────────────────────────
+  // UI Controls
+  // ────────────────────────────────────────────────────────────────
+
+  consoleToggle.addEventListener('click', function () {
+    consoleBody.classList.toggle('open');
+  });
+
+  reloadBtn.addEventListener('click', function () {
+    iframe.src = iframe.src;
+  });
+
+  themeToggle.addEventListener('click', function () {
+    currentTheme = currentTheme === 'dark' ? 'light' : 'dark';
+    sendToPlugin({
+      type: 'theme_update',
+      messageId: 'theme_' + Date.now(),
+      payload: getTheme(),
+    });
+    logMessage('send', 'theme_update', { mode: currentTheme });
+  });
+
+  // ────────────────────────────────────────────────────────────────
+  // Message Handling
+  // ────────────────────────────────────────────────────────────────
+
+  window.addEventListener('message', function (event) {
+    if (event.source !== iframe.contentWindow) return;
+
+    var data = event.data;
+    if (!data || typeof data !== 'object' || !data.type || !data.messageId) return;
+
+    logMessage('recv', data.type, data.payload);
+
+    // Fire-and-forget messages
+    if (data.type === 'ready') return;
+
+    if (data.type === 'resize') {
+      var height = data.payload && data.payload.height;
+      if (typeof height === 'number' && height > 0) {
+        iframe.style.height = height + 'px';
+        iframe.style.flex = 'none';
+      }
+      return;
+    }
+
+    if (data.type === 'toast') {
+      var msg = data.payload && data.payload.message;
+      if (typeof msg === 'string') {
+        logMessage('toast', msg, data.payload);
+      }
+      return;
+    }
+
+    if (data.type === 'navigate') {
+      var navPath = data.payload && data.payload.path;
+      if (typeof navPath === 'string') {
+        logMessage('nav', navPath);
+      }
+      return;
+    }
+
+    // Request/response messages — enforce permissions + rate limits, then proxy
+    handleRequest(data);
+  });
+
+  function handleRequest(data) {
+    try {
+      // Check permissions
+      var requiredPerm = PERMISSION_MAP[data.type];
+      if (requiredPerm && cachedConfig && cachedConfig.permissions.indexOf(requiredPerm) === -1) {
+        throw new Error('Permission denied: ' + requiredPerm + ' not granted');
+      }
+
+      // Check rate limit
+      checkRateLimit(data.type);
+    } catch (err) {
+      logMessage('error', err.message);
+      sendToPlugin({
+        type: 'response',
+        messageId: data.messageId,
+        payload: null,
+        error: err.message,
+      });
+      return;
+    }
+
+    // Proxy to harness server
+    fetch('/api/bridge', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ type: data.type, payload: data.payload }),
+    })
+      .then(function (response) {
+        if (!response.ok) {
+          return response.json().then(function (err) {
+            throw new Error(err.error || 'Bridge call failed');
+          });
+        }
+        return response.json();
+      })
+      .then(function (result) {
+        logMessage('send', 'response', result);
+
+        // Show cost for entity invocations in live mode
+        if (
+          data.type === 'entity_invoke' &&
+          result.metadata &&
+          result.metadata.cost > 0
+        ) {
+          logMessage('cost', 'Credits used: ' + result.metadata.cost.toFixed(4));
+          fetchCredits();
+        }
+
+        sendToPlugin({
+          type: 'response',
+          messageId: data.messageId,
+          payload: result,
+        });
+      })
+      .catch(function (err) {
+        logMessage('error', err.message);
+        sendToPlugin({
+          type: 'response',
+          messageId: data.messageId,
+          payload: null,
+          error: err.message,
+        });
+      });
+  }
+
+  // ────────────────────────────────────────────────────────────────
+  // Iframe Init
+  // ────────────────────────────────────────────────────────────────
+
+  iframe.addEventListener('load', function () {
+    if (!cachedConfig) return;
+
+    sendToPlugin({
+      type: 'init',
+      messageId: 'init_0',
+      payload: {
+        archId: 'dev_harness',
+        permissions: cachedConfig.permissions,
+        theme: getTheme(),
+        currentPath: '/',
+      },
+    });
+    logMessage('send', 'init');
+  });
+
+  // ────────────────────────────────────────────────────────────────
+  // Helpers
+  // ────────────────────────────────────────────────────────────────
+
+  function sendToPlugin(message) {
+    // targetOrigin '*' because sandboxed iframes have opaque origins.
+    // Security is enforced by checking event.source on incoming messages.
+    iframe.contentWindow && iframe.contentWindow.postMessage(message, '*');
+  }
+
+  function checkRateLimit(type) {
+    var limit = RATE_LIMITS[type];
+    if (!limit) return;
+
+    var now = Date.now();
+    var bucket = rateBuckets[type];
+
+    if (!bucket || now - bucket.windowStart > 60000) {
+      rateBuckets[type] = { count: 1, windowStart: now };
+      return;
+    }
+
+    if (bucket.count >= limit.maxPerMinute) {
+      throw new Error(
+        'Rate limit exceeded for ' + type + ': max ' + limit.maxPerMinute + '/minute',
+      );
+    }
+
+    bucket.count++;
+  }
+
+  function getTheme() {
+    if (currentTheme === 'light') {
+      return {
+        mode: 'light',
+        colors: {
+          background: '#ffffff',
+          foreground: '#18181b',
+          primary: '#7c3aed',
+          secondary: '#ede9fe',
+          accent: '#8b5cf6',
+          muted: '#f4f4f5',
+          border: '#e4e4e7',
+        },
+      };
+    }
+    return {
+      mode: 'dark',
+      colors: {
+        background: '#0a0a0f',
+        foreground: '#e4e4e7',
+        primary: '#6d28d9',
+        secondary: '#1e1b4b',
+        accent: '#8b5cf6',
+        muted: '#27272a',
+        border: '#3f3f46',
+      },
+    };
+  }
+
+  function fetchConfig() {
+    return fetch('/api/config').then(function (r) {
+      return r.json();
+    });
+  }
+
+  function fetchCredits() {
+    fetch('/api/credits')
+      .then(function (r) {
+        return r.json();
+      })
+      .then(function (data) {
+        if (data.balance !== undefined && isFinite(data.balance)) {
+          creditBalance.textContent = 'Credits: ' + data.balance.toFixed(2);
+        }
+      })
+      .catch(function () {});
+  }
+
+  function logMessage(direction, type, payload) {
+    messageCount++;
+    consoleCount.textContent = messageCount + ' messages';
+
+    var entry = document.createElement('div');
+    entry.className = 'log-entry';
+
+    var time = new Date().toLocaleTimeString();
+    var cls = 'log-info';
+    if (direction === 'error') cls = 'log-error';
+    if (direction === 'warn' || direction === 'cost') cls = 'log-warn';
+    if (direction === 'toast') cls = 'log-warn';
+
+    var text = '<span class="log-time">' + escapeHtml(time) + '</span>';
+    text +=
+      '<span class="' +
+      cls +
+      '">[' +
+      escapeHtml(direction.toUpperCase()) +
+      '] ' +
+      escapeHtml(String(type)) +
+      '</span>';
+    if (payload && typeof payload === 'object') {
+      text +=
+        ' <span style="color:#6b7280">' +
+        escapeHtml(JSON.stringify(payload).substring(0, 120)) +
+        '</span>';
+    }
+
+    entry.innerHTML = text;
+    consoleBody.appendChild(entry);
+    consoleBody.scrollTop = consoleBody.scrollHeight;
+  }
+
+  function escapeHtml(str) {
+    var div = document.createElement('div');
+    div.appendChild(document.createTextNode(str));
+    return div.innerHTML;
+  }
+})();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@fias/plugin-dev-harness",
+  "version": "1.1.0",
+  "description": "Development harness for building and testing FIAS plugin arches locally",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "fias-dev": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && cp -r src/server/static dist/server/static",
+    "clean": "rm -rf dist",
+    "watch": "tsc -w",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "fias",
+    "plugin",
+    "arche",
+    "dev",
+    "harness"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "express": "^4.21.0",
+    "open": "^10.0.0",
+    "chalk": "^4.1.2"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^25.0.0",
+    "typescript": "^5.3.3"
+  }
+}

package/templates/fias-dev.config.json

@@ -0,0 +1,12 @@
+{
+  "pluginUrl": "http://localhost:3100",
+  "port": 3200,
+  "permissions": ["theme:read", "entities:invoke", "storage:sandbox", "user:profile:read"],
+  "mockUser": {
+    "userId": "dev_user_001",
+    "displayName": "Dev User",
+    "avatar": null
+  },
+  "mockTheme": "light",
+  "apiUrl": "https://api.fias.app/v1"
+}