Soclaw Middleware Anything

1.0.4 verified Sat Apr 25 auth: no javascript

Gateway middleware node runtime v1.0.4 that embeds Express health endpoints and routes remote WebSocket commands to a local command-registry. Supports Node modules, Python/ESM subprocesses, and CLI-scripted execution. Manifest-driven command loading from built-in JSON, environment variables, or runtime API injection. Requires Node.js ≥18. Built with esbuild to produce dist/ entry points. Key differentiator: dynamic command injection without modifying the core package, via external manifest files, env vars, or programmatic applyManifestLayer. Includes a CLI binary for debugging/scripting. Uses cross-env for Windows compatibility. Release cadence: unknown, single published version.

Common errors

error Error: Cannot find module 'soclaw-middleware-anything/dist/index.js' ↓

cause dist/ not built (only when using from git clone)

fix

Run npm run build in the package directory

error Error: Cannot find module './command/index' ↓

cause Command index bundled incorrectly; runtime expects separate file

fix

Ensure esbuild external: ['./command/index'] or equivalent

error Warning: 'openMacApp' field is deprecated, please use 'modules' instead ↓

cause Manifest JSON uses deprecated openMacApp

fix

Replace openMacApp with modules array

error SyntaxError: Unexpected token '.' (Windows path separator) ↓

cause Node.js version <18 does not support certain syntax

fix

Upgrade Node.js to >=18

Warnings

breaking Internal module paths: require('soclaw-middleware-anything/dist/...') required for submodules; package root exports only limited API ↓

fix Use correct paths like require('soclaw-middleware-anything/dist/command')

gotcha Build step required for development: npm run build must be run before first test or local link to generate dist/ ↓

fix Run npm run build after cloning repository

deprecated openMacApp field in manifest is deprecated and will be ignored with a warning; use modules instead ↓

fix Replace openMacApp with modules array in manifest JSON

gotcha Windows subprocess support: .bat/.cmd files run as subprocess on Windows only; on non-Windows they are skipped with a warning ↓

fix Use cross-platform scripts (Python or Node) instead of .bat/.cmd

gotcha Dynamic require of command handlers fails if bundled; command index must be external in esbuild config ↓

fix Keep src/command/index.js as external in build script

gotcha Path resolution in manifests: moduleRoot is relative to manifest file location, not CWD ↓

fix Place manifest files carefully or use absolute paths

Install

npm install soclaw-middleware-anything

yarn add soclaw-middleware-anything

pnpm add soclaw-middleware-anything

Imports

default
```
import soclaw from 'soclaw-middleware-anything'
```
Package is CJS, named exports may not be available via ESM

GatewayClient

wrong

import { GatewayClient } from 'soclaw-middleware-anything'

correct

const { GatewayClient } = require('soclaw-middleware-anything')

Package is CJS, named exports may not be available via ESM

bootstrapCommandRegistry

wrong

const { bootstrapCommandRegistry } = require('soclaw-middleware-anything')

correct

const { bootstrapCommandRegistry } = require('soclaw-middleware-anything/dist/command')

Internal module, not exported from package root

applyManifestLayer

const { applyManifestLayer } = require('soclaw-middleware-anything/dist/command')

Internal module, not exported from package root

Quickstart

Initialize GatewayClient to connect to a WebSocket gateway, listen for messages, and handle commands.

const { GatewayClient } = require('soclaw-middleware-anything');
const client = new GatewayClient({
  gateway: process.env.GATEWAY_URL ?? 'ws://localhost:8080',
  nodeId: process.env.NODE_ID ?? 'node-1'
});
client.on('message', (msg) => {
  console.log('Received:', msg);
});
client.connect();