feat(rustbridge): add RustBridge and RustBinaryLocator with typed IPC interfaces, plugins, tests and mock runner; export from index; add npm registries

test/helpers/mock-rust-binary.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * Mock "Rust binary" for testing the RustBridge IPC protocol.
+ * Reads JSON lines from stdin, writes JSON lines to stdout.
+ * Emits a ready event on startup.
+ */
+
+import { createInterface } from 'readline';
+
+// Emit ready event
+const readyEvent = JSON.stringify({ event: 'ready', data: { version: '1.0.0' } });
+process.stdout.write(readyEvent + '\n');
+
+const rl = createInterface({ input: process.stdin });
+
+rl.on('line', (line) => {
+  let request;
+  try {
+    request = JSON.parse(line.trim());
+  } catch {
+    return;
+  }
+
+  const { id, method, params } = request;
+
+  if (method === 'echo') {
+    // Echo back the params as result
+    const response = JSON.stringify({ id, success: true, result: params });
+    process.stdout.write(response + '\n');
+  } else if (method === 'error') {
+    // Return an error
+    const response = JSON.stringify({ id, success: false, error: 'Test error message' });
+    process.stdout.write(response + '\n');
+  } else if (method === 'emitEvent') {
+    // Emit a custom event, then respond with success
+    const event = JSON.stringify({ event: params.eventName, data: params.eventData });
+    process.stdout.write(event + '\n');
+    const response = JSON.stringify({ id, success: true, result: null });
+    process.stdout.write(response + '\n');
+  } else if (method === 'slow') {
+    // Respond after a delay
+    setTimeout(() => {
+      const response = JSON.stringify({ id, success: true, result: { delayed: true } });
+      process.stdout.write(response + '\n');
+    }, 100);
+  } else if (method === 'exit') {
+    // Graceful exit
+    const response = JSON.stringify({ id, success: true, result: null });
+    process.stdout.write(response + '\n');
+    process.exit(0);
+  } else {
+    // Unknown command
+    const response = JSON.stringify({ id, success: false, error: `Unknown method: ${method}` });
+    process.stdout.write(response + '\n');
+  }
+});
+
+// Handle SIGTERM gracefully
+process.on('SIGTERM', () => {
+  process.exit(0);
+});

test/test.rustbinarylocator.node.ts

@@ -0,0 +1,98 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as path from 'path';
+import * as fs from 'fs';
+import { RustBinaryLocator } from '../ts/classes.rustbinarylocator.js';
+
+const testDir = path.resolve(path.dirname(new URL(import.meta.url).pathname));
+
+tap.test('should return null when no binary is found', async () => {
+  const locator = new RustBinaryLocator({
+    binaryName: 'nonexistent-binary-xyz',
+    searchSystemPath: false,
+  });
+  const result = await locator.findBinary();
+  expect(result).toBeNull();
+});
+
+tap.test('should use explicit binaryPath when provided', async () => {
+  const mockBinaryPath = path.join(testDir, 'helpers/mock-rust-binary.mjs');
+  const locator = new RustBinaryLocator({
+    binaryName: 'mock-rust-binary',
+    binaryPath: mockBinaryPath,
+    searchSystemPath: false,
+  });
+  const result = await locator.findBinary();
+  expect(result).toEqual(mockBinaryPath);
+});
+
+tap.test('should cache the result', async () => {
+  const mockBinaryPath = path.join(testDir, 'helpers/mock-rust-binary.mjs');
+  const locator = new RustBinaryLocator({
+    binaryName: 'mock-rust-binary',
+    binaryPath: mockBinaryPath,
+    searchSystemPath: false,
+  });
+
+  const first = await locator.findBinary();
+  const second = await locator.findBinary();
+  expect(first).toEqual(second);
+  expect(first).toEqual(mockBinaryPath);
+});
+
+tap.test('should clear cache', async () => {
+  const mockBinaryPath = path.join(testDir, 'helpers/mock-rust-binary.mjs');
+  const locator = new RustBinaryLocator({
+    binaryName: 'mock-rust-binary',
+    binaryPath: mockBinaryPath,
+    searchSystemPath: false,
+  });
+
+  const first = await locator.findBinary();
+  expect(first).toEqual(mockBinaryPath);
+
+  locator.clearCache();
+  // After clearing, next call should re-search and still find it
+  const second = await locator.findBinary();
+  expect(second).toEqual(mockBinaryPath);
+});
+
+tap.test('should fall back to env var when binaryPath not set', async () => {
+  const mockBinaryPath = path.join(testDir, 'helpers/mock-rust-binary.mjs');
+  const envVar = 'TEST_SMARTRUST_BINARY_' + Date.now();
+  process.env[envVar] = mockBinaryPath;
+
+  const locator = new RustBinaryLocator({
+    binaryName: 'mock-rust-binary',
+    envVarName: envVar,
+    searchSystemPath: false,
+  });
+
+  const result = await locator.findBinary();
+  expect(result).toEqual(mockBinaryPath);
+
+  delete process.env[envVar];
+});
+
+tap.test('should find binary in local paths', async () => {
+  const mockBinaryPath = path.join(testDir, 'helpers/mock-rust-binary.mjs');
+  const locator = new RustBinaryLocator({
+    binaryName: 'mock-rust-binary',
+    localPaths: ['/nonexistent/path/binary', mockBinaryPath],
+    searchSystemPath: false,
+  });
+
+  const result = await locator.findBinary();
+  expect(result).toEqual(mockBinaryPath);
+});
+
+tap.test('should find node in system PATH', async () => {
+  const locator = new RustBinaryLocator({
+    binaryName: 'node',
+    searchSystemPath: true,
+  });
+
+  const result = await locator.findBinary();
+  expect(result).not.toBeNull();
+});
+
+export default tap.start();

test/test.rustbridge.node.ts

@@ -0,0 +1,191 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as path from 'path';
+import { RustBridge } from '../ts/classes.rustbridge.js';
+import type { ICommandDefinition } from '../ts/interfaces/index.js';
+
+const testDir = path.resolve(path.dirname(new URL(import.meta.url).pathname));
+const mockBinaryPath = path.join(testDir, 'helpers/mock-rust-binary.mjs');
+
+// Define the command types for our mock binary
+type TMockCommands = {
+  echo: { params: Record<string, any>; result: Record<string, any> };
+  error: { params: {}; result: never };
+  emitEvent: { params: { eventName: string; eventData: any }; result: null };
+  slow: { params: {}; result: { delayed: boolean } };
+  exit: { params: {}; result: null };
+};
+
+tap.test('should spawn and receive ready event', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'node',
+    binaryPath: 'node',
+    cliArgs: [mockBinaryPath],
+    readyTimeoutMs: 5000,
+  });
+
+  const result = await bridge.spawn();
+  expect(result).toBeTrue();
+  expect(bridge.running).toBeTrue();
+
+  bridge.kill();
+  expect(bridge.running).toBeFalse();
+});
+
+tap.test('should send command and receive response', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'node',
+    binaryPath: 'node',
+    cliArgs: [mockBinaryPath],
+    readyTimeoutMs: 5000,
+  });
+
+  await bridge.spawn();
+
+  const result = await bridge.sendCommand('echo', { hello: 'world', num: 42 });
+  expect(result).toEqual({ hello: 'world', num: 42 });
+
+  bridge.kill();
+});
+
+tap.test('should handle error responses', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'node',
+    binaryPath: 'node',
+    cliArgs: [mockBinaryPath],
+    readyTimeoutMs: 5000,
+  });
+
+  await bridge.spawn();
+
+  let threw = false;
+  try {
+    await bridge.sendCommand('error', {});
+  } catch (err: any) {
+    threw = true;
+    expect(err.message).toInclude('Test error message');
+  }
+  expect(threw).toBeTrue();
+
+  bridge.kill();
+});
+
+tap.test('should receive custom events from the binary', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'node',
+    binaryPath: 'node',
+    cliArgs: [mockBinaryPath],
+    readyTimeoutMs: 5000,
+  });
+
+  await bridge.spawn();
+
+  const eventPromise = new Promise<any>((resolve) => {
+    bridge.once('management:testEvent', (data) => {
+      resolve(data);
+    });
+  });
+
+  await bridge.sendCommand('emitEvent', {
+    eventName: 'testEvent',
+    eventData: { key: 'value' },
+  });
+
+  const eventData = await eventPromise;
+  expect(eventData).toEqual({ key: 'value' });
+
+  bridge.kill();
+});
+
+tap.test('should handle delayed responses', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'node',
+    binaryPath: 'node',
+    cliArgs: [mockBinaryPath],
+    readyTimeoutMs: 5000,
+    requestTimeoutMs: 5000,
+  });
+
+  await bridge.spawn();
+
+  const result = await bridge.sendCommand('slow', {});
+  expect(result).toEqual({ delayed: true });
+
+  bridge.kill();
+});
+
+tap.test('should handle multiple concurrent commands', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'node',
+    binaryPath: 'node',
+    cliArgs: [mockBinaryPath],
+    readyTimeoutMs: 5000,
+  });
+
+  await bridge.spawn();
+
+  const results = await Promise.all([
+    bridge.sendCommand('echo', { id: 1 }),
+    bridge.sendCommand('echo', { id: 2 }),
+    bridge.sendCommand('echo', { id: 3 }),
+  ]);
+
+  expect(results[0]).toEqual({ id: 1 });
+  expect(results[1]).toEqual({ id: 2 });
+  expect(results[2]).toEqual({ id: 3 });
+
+  bridge.kill();
+});
+
+tap.test('should throw when sending command while not running', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'node',
+    binaryPath: 'node',
+    cliArgs: [mockBinaryPath],
+  });
+
+  let threw = false;
+  try {
+    await bridge.sendCommand('echo', {});
+  } catch (err: any) {
+    threw = true;
+    expect(err.message).toInclude('not running');
+  }
+  expect(threw).toBeTrue();
+});
+
+tap.test('should return false when binary not found', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'nonexistent-binary-xyz',
+    searchSystemPath: false,
+  });
+
+  const result = await bridge.spawn();
+  expect(result).toBeFalse();
+  expect(bridge.running).toBeFalse();
+});
+
+tap.test('should emit exit event when process exits', async () => {
+  const bridge = new RustBridge<TMockCommands>({
+    binaryName: 'node',
+    binaryPath: 'node',
+    cliArgs: [mockBinaryPath],
+    readyTimeoutMs: 5000,
+  });
+
+  await bridge.spawn();
+
+  const exitPromise = new Promise<number | null>((resolve) => {
+    bridge.once('exit', (code) => {
+      resolve(code);
+    });
+  });
+
+  // Tell mock binary to exit
+  await bridge.sendCommand('exit', {});
+
+  const exitCode = await exitPromise;
+  expect(exitCode).toEqual(0);
+  expect(bridge.running).toBeFalse();
+});
+
+export default tap.start();

test/test.ts

@@ -1,8 +1,12 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
-import * as smartrust from '../ts/index.js'
+import * as smartrust from '../ts/index.js';
 
-tap.test('first test', async () => {
-  console.log(smartrust)
-})
+tap.test('should export RustBridge', async () => {
+  expect(smartrust.RustBridge).toBeTypeOf('function');
+});
 
-export default tap.start()
+tap.test('should export RustBinaryLocator', async () => {
+  expect(smartrust.RustBinaryLocator).toBeTypeOf('function');
+});
+
+export default tap.start();