MetaCrate/programs/README.md

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	Pending milestone 11 issue #87
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.

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:

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:

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:

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:

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