Implement OSDInspector offline tool (#85)

programs/README.md

@@ -0,0 +1,62 @@
+# 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 | Pending milestone 11 issue #86 |
+| `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.
+
+```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
+```