# Native programs

The `libremetaverse-programs` package owns one native Rust binary for every
program in the pinned LibreMetaverse source snapshot. The source inventory and
hashes remain in `upstream-programs.json`; implementation status is tracked
here so a source entry is never mistaken for a completed port.

| Binary | Upstream project | Status |
| --- | --- | --- |
| `osd-inspector` | OSDInspector | Implemented and tested offline |
| `simple-bot` | SimpleBot | Implemented with live and deterministic fake-grid modes |
| `packet-dump` | PacketDump | Implemented with live and deterministic fake-grid capture |
| `prim-inspector` | PrimInspector | Pending milestone 11 issue #88 |
| `inventory-explorer` | InventoryExplorer | Pending milestone 11 issue #89 |
| `irc-gateway` | IRCGateway | Pending milestone 11 issue #90 |
| `test-client` | TestClient | Pending milestone 11 issues #91–#94 |
| `vivox-test` | VivoxTest | Pending milestone 11 issue #95 |
| `webrtc-test` | WebRtcTest | Pending milestone 11 issue #96 |

## OSDInspector

`osd-inspector` is a bounded, offline command-line client of the public native
StructuredData and Primitive APIs. It does not initialize a grid client, read
credentials, load a native codec, or invoke a .NET process.

```text
osd-inspector inspect <file>                 # alias: i
osd-inspector convert <input> <format> <out> # alias: c
osd-inspector validate <file>                # alias: v
osd-inspector prim-to-osd
osd-inspector osd-to-prim <file>
```

The supported output formats are `json` (`j`), `xml` (`x`), `binary`
(`bin` or `b`), and `notation` (`llsd` or `n`). Use `-` as an input or output
path for standard input or standard output. Format detection uses the filename
extension as a hint and then checks every native parser, so binary and notation
LLSD work through files and pipes as well as JSON and XML.

Input is read through a bounded buffer and is limited to the StructuredData
binary allocation limit by default. `--max-input-bytes <BYTES>` can lower that
ceiling for constrained callers. StructuredData also enforces its depth, node,
and aggregate allocation limits while parsing.

Normal results are written to stdout and diagnostics to stderr. Exit status is
stable for scripts:

| Status | Meaning |
| --- | --- |
| 0 | Success |
| 2 | Command-line usage error |
| 3 | File or standard-stream I/O error |
| 4 | Invalid or oversized OSD input |
| 5 | Primitive conversion or output serialization error |

Run the issue-focused CLI suite and the related translated StructuredData cases
with:

```sh
cargo test -p libremetaverse-programs --test osd_inspector_cli --locked
cargo test --manifest-path tests/compat/Cargo.toml --test structured_data --locked
```

## SimpleBot

`simple-bot` is an asynchronous native Rust client with the command surface of
the upstream example. A live session accepts the original positional
credentials, or reads them from the environment:

```text
simple-bot FIRSTNAME LASTNAME PASSWORD [--login-uri URL]
GRID_FIRST_NAME=... GRID_LAST_NAME=... GRID_PASSWORD=... simple-bot
```

`GRID_LOGIN_URL` supplies the endpoint when `--login-uri` is absent, and
`--login-timeout-seconds` bounds login to 30 seconds by default. Credentials,
authorization values, capability URLs, and token values are redacted from
output. After login the bot answers `help`/`?`, `where`/`location`, `sit`,
`stand`, `dance`, `fly`, `walk`, `jump`, and `hello`/`hi`/`hey` instant
messages. It also greets other avatars that say hello in local chat. Ctrl-C
cancels pending greetings and login work, releases an in-progress jump,
unsubscribes event handlers, logs out, and disposes the client before exit.

For offline validation, `--fake-script FILE` runs the same command handlers
against a deterministic fake grid. Scripts contain no credentials. Blank
lines and lines beginning with `#` are ignored; remaining lines use one of:

```text
im<TAB>source-uuid<TAB>source-name<TAB>message
chat<TAB>source-uuid<TAB>source-name<TAB>message
status<TAB>message
```

The reader accepts at most 1 MiB, 1,024 events, 256-byte names, and 4,096-byte
messages. The fake transcript records every client call, uses the real DANCE1
UUID, and finishes with zero active tasks and sockets. Run the issue-focused
suite and the related runtime compatibility cases with:

```sh
cargo test -p libremetaverse-programs --test simple_bot_cli --locked
cargo test --manifest-path tests/compat/Cargo.toml --test core_runtime_shims --locked
```

## PacketDump

`packet-dump` preserves the upstream live arguments and its 20-second login
timeout while adding safe, bounded capture controls:

```text
packet-dump FIRSTNAME LASTNAME PASSWORD SECONDS
  [--direction incoming|outgoing|both]
  [--packet-type NAME]... [--raw]
  [--output FILE] [--max-output-bytes BYTES] [--max-packets COUNT]
```

`SECONDS=0` captures until Ctrl-C. Credentials can instead come from
`GRID_FIRST_NAME`, `GRID_LAST_NAME`, and `GRID_PASSWORD`; `GRID_LOGIN_URL` or
`--login-uri` selects a login endpoint. The client disables multiple simulator
connections and sends zero land, wind, and cloud throttles like the source
program. Incoming decoded callbacks retain their original datagrams, while
outgoing callbacks are decoded through the public packet factory. Records show
direction, packet type, simulator, byte count, sequence, frequency, ID, and
header flags. Exact packet-type filters may be repeated.

Raw hexadecimal output is opt-in. Live capture masks the password and native
session identifiers wherever they occur in a datagram, and suppresses raw
payloads containing URLs, authorization terms, capability terms, or token
assignments. Login and disconnect messages use the same text redaction.
Output defaults to stdout, may be redirected to a newly truncated file, and is
bounded to 16 MiB and 100,000 matching packets unless lower or higher explicit
limits are supplied. A complete line is either written or rejected at the byte
limit.

Offline validation uses `--fake-script FILE` with records of this form:

```text
incoming<TAB>simulator<TAB>hex-bytes
outgoing<TAB>simulator<TAB>hex-bytes
```

Scripts are capped at 8 MiB and individual datagrams at 64 KiB. Each datagram
is passed through the native wire decoder; malformed and unknown packets are
reported without aborting the capture. The issue-focused and related translated
wire tests are:

```sh
cargo test -p libremetaverse-programs --test packet_dump_cli --locked
cargo test -p libremetaverse --test packet_wire --locked
cargo test --manifest-path tests/compat/Cargo.toml --test wire_semantics --locked
```