@sndwrks/osc-cli 1.0.3 → 1.3.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2026 sndwrks Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,144 +1,330 @@
-# OSC CLI Tool
+![sndwrks logo](images/sndwrks-square_200px-high.png)
 
-**DISCLAIMER: this was written by AI, but it will be maintained by humans (probably)**
+# osc-cli
 
-A simple command-line application for sending and receiving OSC (Open Sound Control) messages via TCP and UDP.
+![NPM Version](https://img.shields.io/npm/v/%40sndwrks%2Fosc-cli?style=flat-square&color=rgb(239%2C%20145%2C%2081))
+![GitHub License](https://img.shields.io/github/license/sndwrks/osc-cli?style=flat&color=rgb(14%2C%2022%2C%2025))
+![Node LTS](https://img.shields.io/node/v-lts/%40sndwrks%2Fosc-cli)
 
-## Features
+
+
+**DISCLAIMER: this was written by AI, and promptly rewritten, but it will be maintained by humans (probably).**
+
+A simple command-line application for sending and receiving OSC (Open Sound Control) messages via TCP and UDP including load testing.
+
+## What does it do?
 
 - Listen for OSC messages via UDP
 - Listen for OSC messages via TCP
 - Listen on both protocols simultaneously
 - Send OSC messages via UDP
 - Send OSC messages via TCP
-- Logging with @sndwrks/lumberjack
-- **Installable as a global CLI tool**
+- Load Testing with UDP
+- Load Testing with TCP
+- Integration Testing with UDP (send to app, validate response)
+- Integration Testing with TCP (send to app, validate response)
 
 ## Installation
 
-### Install Globally
-
-```bash
-npm install -g .
-```
-
-After installation, you can use the `osc-cli` command from anywhere:
+### Install from npm
 
 ```bash
-osc-cli listen-udp 8000
+npm install -g @sndwrks/osc-cli
 ```
 
-### Install as Dependency
+### Install from Github
 
 ```bash
-npm install
-```
+# clone the repo
+git clone git@github.com:sndwrks/osc-cli.git
 
-### Install from npm
+# install globally
+npm i -g .
 
-```bash
-npm install -g @sndwrks/osc-cli
+# otherwise build and run locally
+npm i
+npm run build
+npm start -- <commands>
 ```
 
-## Build
+## Uninstall
 
 ```bash
-npm run build
+npm uninstall -g osc-cli
 ```
 
 ## Usage
 
-Once installed globally, use the `osc-cli` command. If not installed globally, use `npm start` instead.
+Once installed globally, use `osc-cli <command>`. If not installed globally, use `npm start -- <command>` instead.
 
-```bash
-npm start -- listen-udp <port>
-npm start -- listen-tcp <port>
-npm start -- listen-both <udp-port> <tcp-port>
-```
 
 ### Listen for OSC Messages
 
-**UDP (default port 57121):**
+Starts a server to listen for incoming OSC messages.
+
+#### Args
+
+| Flag | Option | Type | Description | Example | Default |
+|------|--------|------|-------------|---------|---------|
+| `-i` | `--ip-address <ip-address>` | string | IP address to bind to | 127.0.0.1 | 0.0.0.0 |
+| `-p` | `--port <port>` | number | Port the server listens on | 53000 | 51000 |
+
+**UDP (default port 51000):**
 ```bash
 osc-cli listen-udp
-osc-cli listen-udp 8000
+osc-cli listen-udp -p 8000
+osc-cli listen-udp --port 8000 --ip-address 127.0.0.1
 ```
 
-**TCP (default port 57122):**
+**TCP (default port 51001):**
 ```bash
 osc-cli listen-tcp
-osc-cli listen-tcp 8001
+osc-cli listen-tcp -p 8001
+osc-cli listen-tcp --port 8001 --ip-address 127.0.0.1
 ```
 
 **Both UDP and TCP:**
 ```bash
 osc-cli listen-both
-osc-cli listen-both 8000 8001
+osc-cli listen-both --udp-port 8000 --tcp-port 8001
+osc-cli listen-both --udp-port 8000 --tcp-port 8001 --udp-ip-address 127.0.0.1 --tcp-ip-address 127.0.0.1
 ```
 
 ### Send OSC Messages
 
+Send a single OSC message.
+
+#### Args
+
+Sends a single OSC message via UDP
+
+| Flag | Option | Type | Description | Example | Default |
+|------|--------|------|-------------|---------|---------|
+| | `--udp-ip-address <udp-ip-address>` | string | IP address to bind the UDP server to | 127.0.0.1 | |
+| | `--udp-port <udp-port>` | number | Port the UDP server will listen on | 53000 | 51000 |
+| | `--tcp-ip-address <tcp-ip-address>` | string | IP address to bind the TCP server to | 127.0.0.1 | 0.0.0.0 |
+| | `--tcp-port <tcp-port>` | number | Port the TCP server will listen on | 53001 | 51001 |
+
+
 **UDP:**
 ```bash
-osc-cli send-udp /test hello 123 127.0.0.1 57121
-osc-cli send-udp /synth/note 440 0.5 localhost 8000
+# no args
+osc-cli send-udp -a /test -i 127.0.0.1 -p 57121
+
+# with args
+osc-cli send-udp -a /test -i 127.0.0.1 -p 57121 --args hello 123
+osc-cli send-udp --address /synth/note --ip-address localhost --port 8000 --args 440 0.5
 ```
 
 **TCP:**
-NOTE: This is currently broken due to issue in osc.js
 ```bash
-osc-cli send-tcp /test hello 123 127.0.0.1 57122
-osc-cli send-tcp /synth/note 440 0.5 localhost 8001
+osc-cli send-tcp -a /test -i 127.0.0.1 -p 57122 --args hello 123
+osc-cli send-tcp --address /synth/note --ip-address localhost --port 8001 --args 440 0.5
 ```
 
-## Message Format
+### Load Testing
+
+The load testing allows for sending multiple messages in batches. The batches may overlap if the message rate is slower than the batch interval.
 
-- **Address**: OSC address pattern (e.g., `/test`, `/synth/freq`)
-- **Args**: Space-separated values (automatically parsed as numbers if possible)
-- **Host**: Target hostname or IP address (default: 127.0.0.1)
-- **Port**: Target port number
+#### Args
 
-## Examples
+| Flag | Option | Type | Required | Description | Example | Default |
+|------|--------|------|----------|-------------|---------|---------|
+| | `--local-ip-address <local-ip-address>` | string | No | Local IP Address to bind the client to | | 0.0.0.0 |
+| | `--local-port <local-port>` | number | No | Local port to bind the client to | | 51000 |
+| | `--remote-ip-address <remote-ip-address>` | string | Yes | IP Address to send the messages to | 10.10.209.5 | |
+| | `--remote-port <remote-port>` | number | Yes | Port to send the messages to | | |
+| | `--messages-per-batch <messages-per-batch>` | number | Yes | The number of messages per batch to send | | |
+| | `--message-rate <message-rate>` | number | No | The number of messages to send per second | | |
+| | `--total-batches <total-batches>` | number | Yes | The total number of batches to send | | |
+| | `--batch-interval <batch-interval>` | number | Yes | The time in seconds between batches | | |
+| | `--custom-address <custom-address>` | string | No | A custom address to send | | /sndwrks/osc-cli-load-tester/test |
 
+**UDP Load Test:**
 ```bash
-# Install globally
-npm install -g .
+# minimal required args
+osc-cli osc-load-test-udp \
+  --remote-ip-address 127.0.0.1 \
+  --remote-port 8000 \
+  --messages-per-batch 100 \
+  --total-batches 10 \
+  --batch-interval 1
+```
 
-# Start listening on UDP port 8000
-osc-cli listen-udp 8000
+```bash
+# with optional args
+osc-cli osc-load-test-udp \
+  --remote-ip-address 10.10.209.5 \
+  --remote-port 8000 \
+  --messages-per-batch 100 \
+  --total-batches 10 \
+  --batch-interval 1 \
+  --message-rate 50
+```
 
-# In another terminal, send a message
-osc-cli send-udp /hello world 127.0.0.1 8000
+```bash
+osc-cli osc-load-test-udp \
+  --local-ip-address 0.0.0.0 \
+  --local-port 51000 \
+  --remote-ip-address 10.10.209.5 \
+  --remote-port 8000 \
+  --messages-per-batch 100 \
+  --message-rate 50 \
+  --total-batches 10 \
+  --batch-interval 1 \
+  --custom-address /my/custom/address
+```
 
-# Listen on both protocols
-osc-cli listen-both 9000 9001
+**TCP Load Test:**
+```bash
+# minimal required args
+osc-cli osc-load-test-tcp \
+  --remote-ip-address 127.0.0.1 \
+  --remote-port 8001 \
+  --messages-per-batch 100 \
+  --total-batches 10 \
+  --batch-interval 1
+```
 
-# Send via TCP
-osc-cli send-tcp /synth/freq 440 127.0.0.1 9001
+```bash
+# with optional args
+osc-cli osc-load-test-tcp \
+  --remote-ip-address 10.10.209.5 \
+  --remote-port 8001 \
+  --messages-per-batch 100 \
+  --total-batches 10 \
+  --batch-interval 1 \
+  --message-rate 50
 ```
 
-## Development
+```bash
+# with all args
+osc-cli osc-load-test-tcp \
+  --local-ip-address 0.0.0.0 \
+  --local-port 51000 \
+  --remote-ip-address 10.10.209.5 \
+  --remote-port 8001 \
+  --messages-per-batch 100 \
+  --message-rate 50 \
+  --total-batches 10 \
+  --batch-interval 1 \
+  --custom-address /my/custom/address
+```
 
-If you haven't installed globally, you can use npm scripts:
+### Integration Testing
+
+Integration testing commands send messages to a remote application and validate the responses. The remote application should echo back OSC messages to the local listener port.
+
+#### Args
+
+| Flag | Option | Type | Required | Description | Example | Default |
+|------|--------|------|----------|-------------|---------|---------|
+| `-i` | `--remote-ip-address <ip>` | string | Yes | Remote IP to send messages to | 10.10.209.5 | |
+| `-p` | `--remote-port <port>` | number | Yes | Remote port to send messages to | 8000 | |
+| | `--mode <mode>` | string | Yes | Test mode: "single" or "load" | single | |
+| | `--local-ip-address <ip>` | string | No | Local IP to listen for responses | | 0.0.0.0 |
+| | `--local-port <port>` | number | No | Local port to listen for responses | | 57120 (UDP) / 57121 (TCP) |
+| `-a` | `--address <address>` | string | No | OSC address to send | /test | /test |
+| | `--args <args...>` | string[] | No | Arguments to send | hello 123 | |
+| | `--expected-address <address>` | string | No | Expected response address | /response | sent address |
+| | `--expected-args <args...>` | string[] | No | Expected response args | ok 1 | sent args |
+| | `--timeout <ms>` | number | No | Response timeout | | 5000 |
+| | `--messages-per-batch <n>` | number | No | Messages per batch (load mode) | | |
+| | `--total-batches <n>` | number | No | Total batches (load mode) | | |
+| | `--batch-interval <seconds>` | number | No | Interval between batches (load mode) | | |
+| | `--message-rate <n>` | number | No | Messages per second (load mode) | | |
+
+**UDP Integration Test (single message):**
+```bash
+# Send a message and validate the response matches
+osc-cli test-osc-udp \
+  --mode single \
+  -i 127.0.0.1 \
+  -p 8000 \
+  -a /test \
+  --args hello 123
+
+# With custom expected response
+osc-cli test-osc-udp \
+  --mode single \
+  -i 127.0.0.1 \
+  -p 8000 \
+  -a /ping \
+  --expected-address /pong \
+  --expected-args ok
+```
 
+**UDP Integration Test (load test):**
 ```bash
-npm run build          # Build TypeScript
-npm start listen-udp   # Run with npm start
+# Load test with throughput validation
+osc-cli test-osc-udp \
+  --mode load \
+  -i 127.0.0.1 \
+  -p 8000 \
+  --messages-per-batch 100 \
+  --total-batches 10 \
+  --batch-interval 1
 ```
 
-## Uninstall
+**TCP Integration Test (single message):**
+```bash
+osc-cli test-osc-tcp \
+  --mode single \
+  -i 127.0.0.1 \
+  -p 8001 \
+  -a /test \
+  --args hello 123
+```
 
+**TCP Integration Test (load test):**
 ```bash
-npm uninstall -g osc-cli
+osc-cli test-osc-tcp \
+  --mode load \
+  -i 127.0.0.1 \
+  -p 8001 \
+  --messages-per-batch 50 \
+  --total-batches 5 \
+  --batch-interval 2 \
+  --message-rate 100
 ```
 
-## Publishing to NPM
+**Exit codes:**
+- `0` - Test passed (single: response matched; load: no dropped messages)
+- `1` - Test failed (timeout, mismatch, or dropped messages)
+
+## Development
 
-See [PUBLISHING.md](PUBLISHING.md) for detailed instructions on how to publish this package to npm with the TypeScript build step.
+Please get in there if you want. This repo uses eslint 8 for linting AND code style.
+
+**VSCode Example Settings**
+```json
+{
+  "editor.formatOnSave": true,
+  "eslint.codeActionsOnSave.rules": null,
+  "eslint.validate": [
+    "typescript"
+  ],
+  "[typescript]": {
+    "editor.tabSize": 2,
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit"
+    }
+  },
+  "eslint.format.enable": true,
+  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
+  "editor.tabSize": 2,
+  "javascript.updateImportsOnFileMove.enabled": "always",
+  "editor.rulers": [100]
+}
+```
 
-## Dependencies
+```bash
+npm run build        
+npm start listen-udp -- <args> 
+```
 
-- `osc`: OSC protocol implementation
-- `@sndwrks/lumberjack`: Winston-based logging library
+## Wants and Desires
 
-**Note:** This package includes custom TypeScript type definitions for the `osc` library in `src/types/osc.d.ts` since the osc package doesn't provide its own types.
+- roll in nodemon
+- add some way to send messages on an interval