feat: create @waku/run package for local dev env (#2678)

* feat: create @waku/run package for local dev env

* chore: add @waku/run to release please config

* feat: test @waku/run with playwright

* fix: don't run waku/run tests in CI

* fix: cache images so docker-compose can work offline

* feat: set nodekey and staticnode flags for each nwaku node

* fix: use constants for node ids

* chore: set directories for running via npx

* fix: remove .env, support env vars for nwaku ports

* fix: use separate db (same instance) for each node

* feat: add command to test dev env

* chore: use package version in container name

* fix: replace hardcoded WS/REST ports with constants/env vars

* chore: clean up README

* fix: refactor config printing into own function

* fix: add run package to release please manifest

* fix: defer to root folder gitignore/cspell

* fix: update node version and remove tsx

* fix: remove browser tests and express dep

* fix: replace magic values with constants

* fix: move to root .gitignore

* fix: move cspell to root

Author: adklempner

.cspell.json

@@ -55,13 +55,15 @@
     "fontsource",
     "globby",
     "gossipsub",
+    "hackathons",
     "huilong",
     "iasked",
     "ihave",
     "ihaves",
     "ineed",
     "IPAM",
     "ipfs",
+    "isready",
     "iwant",
     "jdev",
     "jswaku",
@@ -165,6 +167,7 @@
     "gen",
     "proto",
     "*.spec.ts",
+    "*.log",
     "CHANGELOG.md"
   ],
   "patterns": [

.gitignore

@@ -17,4 +17,6 @@ packages/discovery/mock_local_storage
 .giga
 .cursor
 .DS_Store
-CLAUDE.md
+CLAUDE.md
+.env
+postgres-data/

.release-please-manifest.json

@@ -10,5 +10,6 @@
   "packages/discovery": "0.0.12",
   "packages/sds": "0.0.7",
   "packages/rln": "0.1.9",
-  "packages/react": "0.0.7"
+  "packages/react": "0.0.7",
+  "packages/run": "0.0.1"
 }

package-lock.json

@@ -14,6 +14,7 @@
     "packages/rln",
     "packages/sdk",
     "packages/relay",
+    "packages/run",
     "packages/tests",
     "packages/reliability-tests",
     "packages/browser-tests",

package.json

@@ -0,0 +1,20 @@
+module.exports = {
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: "./tsconfig.dev.json"
+  },
+  rules: {
+    "@typescript-eslint/no-non-null-assertion": "off"
+  },
+  globals: {
+    process: true
+  },
+  overrides: [
+    {
+      files: ["*.js"],
+      rules: {
+        "no-console": "error"
+      }
+    }
+  ]
+};

packages/run/.eslintrc.cjs

@@ -0,0 +1,11 @@
+module.exports = {
+  extension: ['ts'],
+  require: ['ts-node/register'],
+  loader: 'ts-node/esm',
+  'node-option': [
+    'experimental-specifier-resolution=node',
+    'loader=ts-node/esm'
+  ],
+  timeout: 90000,
+  exit: true
+};

packages/run/.mocharc.cjs

@@ -0,0 +1,148 @@
+# @waku/run
+
+> **Spin up a local Waku network for development without relying on external infrastructure**
+
+Perfect for hackathons, offline development, or when you need a controlled testing environment for your js-waku application.
+
+## What's Included
+
+- **2 nwaku nodes** connected to each other with all protocols enabled:
+- **PostgreSQL database** for message persistence
+- **Isolated network** - nodes only connect to each other
+
+## Requirements
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) or Docker Engine with Compose plugin
+
+## Quick Start
+
+### 1. Start the Network
+
+```bash
+npx @waku/run start
+```
+
+This will:
+- Start 2 nwaku nodes and a PostgreSQL database
+- Run in the background (detached mode)
+- Display connection information you need for your app
+
+**Example output:**
+```typescript
+import { createLightNode } from "@waku/sdk";
+
+const waku = await createLightNode({
+  defaultBootstrap: false,
+  bootstrapPeers: [
+    "/ip4/127.0.0.1/tcp/60000/ws/p2p/16Uiu2HAmF6oAsd23RMAnZb3NJgxXrExxBTPMdEoih232iAZkviU2",
+    "/ip4/127.0.0.1/tcp/60001/ws/p2p/16Uiu2HAm5aZU47YkiUoARqivbCXwuFPzFFXXiURAorySqAQbL6EQ"
+  ],
+  numPeersToUse: 2,
+  libp2p: {
+    filterMultiaddrs: false
+  },
+  networkConfig: {
+    clusterId: 0,
+    numShardsInCluster: 8
+  }
+});
+```
+
+### 2. Connect Your js-waku App
+
+Copy the configuration from the output above and paste it into your application. Then start your node:
+
+```typescript
+await waku.start();
+
+// Your app is now connected to your local Waku network!
+```
+
+### 3. Stop When Done
+
+```bash
+npx @waku/run stop
+```
+
+## Available Commands
+
+### Using npx (published package)
+
+| Command | Description |
+|---------|-------------|
+| `npx @waku/run start` | Start the network (detached) and show connection info |
+| `npx @waku/run stop` | Stop the network and clean up |
+| `npx @waku/run info` | Show connection info for running network |
+| `npx @waku/run logs` | View and follow logs from all nodes |
+| `npx @waku/run test` | Test the network by sending a message |
+
+## Configuration
+
+All configuration is done via environment variables passed to the command.
+
+### Custom Ports
+
+If the default ports are in use, specify custom ports:
+
+```bash
+NODE1_WS_PORT=50000 NODE2_WS_PORT=50001 npx @waku/run start
+```
+
+Available port configuration:
+- `NODE1_WS_PORT` (default: 60000)
+- `NODE2_WS_PORT` (default: 60001)
+- `NODE1_REST_PORT` (default: 8646)
+- `NODE2_REST_PORT` (default: 8647)
+
+### Cluster Configuration
+
+The default configuration uses:
+- Cluster ID: 0
+- Number of shards: 8
+
+To test with a different cluster:
+
+```bash
+CLUSTER_ID=16 npx @waku/run start
+```
+
+### Custom nwaku Version
+
+To use a different nwaku image version:
+
+```bash
+NWAKU_IMAGE=wakuorg/nwaku:v0.35.0 npx @waku/run start
+```
+
+## Debugging
+
+### View Node Logs
+
+```bash
+npx @waku/run logs
+```
+
+### Check Node Health
+
+```bash
+# Node 1
+curl http://127.0.0.1:8646/health
+
+# Node 2
+curl http://127.0.0.1:8647/health
+```
+
+### Check Peer Connections
+
+```bash
+# Node 1 debug info
+curl http://127.0.0.1:8646/debug/v1/info
+
+# Node 2 debug info
+curl http://127.0.0.1:8647/debug/v1/info
+```
+
+
+## License
+
+MIT OR Apache-2.0