Add panel harness tool

Author: hyperpolymath

tools/panel-harness/README.md

@@ -0,0 +1,60 @@
+# Panel Harness
+
+The Panel Harness is a tool for bridging cartridges to BoJ Server and panll.
+
+## Features
+
+- Register cartridges with BoJ Server or panll
+- Support protocol translation (REST ↔ gRPC ↔ GraphQL)
+- Route events between cartridges and BoJ Server/panll
+- Expose cartridges as A2ML-compliant services or panll modules
+
+## Installation
+
+```bash
+cd tools/panel-harness
+npm install
+```
+
+## Usage
+
+### Command Line
+
+```bash
+node harness.js <cartridge-dir> <target> [--routes <routes-file>]
+```
+
+### Options
+
+- `<cartridge-dir>`: Path to the cartridge directory containing `cartridge.json`
+- `<target>`: Target environment (`boj-server` or `panll`)
+- `--routes <routes-file>`: Path to the routes configuration file for the cartridge
+
+### Example
+
+```bash
+node harness.js ../../cartridges/my-cartridge boj-server --routes routes.json
+```
+
+### Programmatic Usage
+
+```javascript
+import { registerCartridge } from './harness.js';
+
+const result = await registerCartridge('path/to/cartridge', 'boj-server', {
+  routes: [
+    { protocol: 'REST', port: 4000 },
+    { protocol: 'gRPC', port: 50051 },
+  ],
+});
+
+console.log('Cartridge registered:', result);
+```
+
+## Output
+
+The Panel Harness registers the cartridge with the specified target and writes the registration to a `registration.json` file in the harness directory.
+
+## License
+
+This tool is licensed under the PMPL-1.0-or-later license. See the LICENSE file for more information.

tools/panel-harness/harness.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+
+// Panel Harness — Bridge cartridges to BoJ Server and panll
+
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+
+async function readJsonFile(filePath) {
+  const content = await readFile(filePath, 'utf8');
+  return JSON.parse(content);
+}
+
+async function writeJsonFile(filePath, data) {
+  await writeFile(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+async function ensureDirectoryExists(directory) {
+  await mkdir(directory, { recursive: true });
+}
+
+async function registerCartridge(cartridgeDir, target, options = {}) {
+  const { routes = [] } = options;
+  
+  // Read cartridge.json
+  const cartridgeJsonPath = join(cartridgeDir, 'cartridge.json');
+  const cartridge = await readJsonFile(cartridgeJsonPath);
+  
+  // Ensure the target directory exists
+  const targetDir = join('harness', target, cartridge.name);
+  await ensureDirectoryExists(targetDir);
+  
+  // Register the cartridge with the target
+  console.log(`Registering cartridge with ${target}...`);
+  
+  // In a real implementation, you would register the cartridge with BoJ Server or panll here
+  // For now, we'll just log the registration
+  const registration = {
+    cartridge,
+    target,
+    routes,
+    registeredAt: new Date().toISOString(),
+  };
+  
+  // Write the registration to a file
+  const registrationPath = join(targetDir, 'registration.json');
+  await writeJsonFile(registrationPath, registration);
+  
+  return {
+    cartridge,
+    target,
+    routes,
+    registrationPath,
+  };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length < 2) {
+    console.error('Usage: node harness.js <cartridge-dir> <target> [--routes <routes-file>]');
+    process.exit(1);
+  }
+  
+  const cartridgeDir = args[0];
+  const target = args[1];
+  const routesIndex = args.indexOf('--routes');
+  const routesFile = routesIndex !== -1 ? args[routesIndex + 1] : null;
+  
+  let routes = [];
+  if (routesFile) {
+    try {
+      routes = await readJsonFile(routesFile);
+    } catch (error) {
+      console.error('Error reading routes file:', error);
+      process.exit(1);
+    }
+  }
+  
+  try {
+    console.log(`Registering cartridge from ${cartridgeDir} with ${target}...`);
+    const result = await registerCartridge(cartridgeDir, target, { routes });
+    
+    console.log('Cartridge registered successfully:');
+    console.log(`  Name: ${result.cartridge.name}`);
+    console.log(`  Target: ${result.target}`);
+    console.log(`  Routes: ${JSON.stringify(result.routes)}`);
+    console.log(`  Registration Path: ${result.registrationPath}`);
+  } catch (error) {
+    console.error('Error registering cartridge:', error);
+    process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { registerCartridge };

tools/panel-harness/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "panel-harness",
+  "version": "0.1.0",
+  "description": "Panel Harness — Bridge cartridges to BoJ Server and panll",
+  "main": "harness.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["boj-server", "cartridge", "panel-harness"],
+  "author": "Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>",
+  "license": "PMPL-1.0-or-later",
+  "type": "module"
+}