Implement native InventoryExplorer

programs/README.md

@@ -11,7 +11,7 @@ here so a source entry is never mistaken for a completed port.
 | `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 | Implemented with live and deterministic fake-grid discovery |
-| `inventory-explorer` | InventoryExplorer | Pending milestone 11 issue #89 |
+| `inventory-explorer` | InventoryExplorer | Implemented with live inventory and deterministic AIS fixtures |
 | `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 |
@@ -189,3 +189,52 @@ Run the isolated CLI golden tests and the related translated primitive cases:
 cargo test -p libremetaverse-programs --test prim_inspector_cli --locked
 cargo test --manifest-path tests/compat/Cargo.toml --test world_object_semantics --locked
 ```
+
+## InventoryExplorer
+
+`inventory-explorer` preserves the source program's live login and operation
+options:
+
+```text
+inventory-explorer FIRSTNAME LASTNAME PASSWORD [--stats]
+  [--search TERM [--type TYPE]] [--export FILE]
+```
+
+Credentials may instead come from `GRID_FIRST_NAME`, `GRID_LAST_NAME`, and
+`GRID_PASSWORD`; `GRID_LOGIN_URL` or `--login-uri` selects the endpoint. Login
+and inventory readiness each have a 30-second deadline. The native client waits
+for a populated root in the real `InventoryManager::store`, handles Ctrl-C and
+disconnects, removes event handlers, logs out, and disposes the client on every
+post-construction path.
+
+With no operation option, the program prints the sorted top-level folders and
+items. `--stats` traverses the hierarchy and reports item and root-folder counts
+plus the ten most common asset types. `--search` performs a case-insensitive
+name search across folders and items, reports parent folders and UUIDs, and
+shows link targets. `--type` accepts every native `AssetType` name and narrows
+item results. Search output defaults to 50 results and is capped at 1,000.
+
+`--export FILE` writes a deterministic `deterministic-v1` hierarchy with
+folders before items, stable case-insensitive name and UUID ordering, asset
+types, link targets, and UUIDs. The destination must be an explicit non-symlink
+path of at most 4,096 characters. The in-memory export is validated before the
+file is written and defaults to a 16 MiB limit. Traversal defaults to 100,000
+entries and 64 folder levels, detects cycles, and exposes configurable bounded
+limits. Standard output is buffered and limited to 4 MiB, and inventory/status
+text redacts URLs and credential-like assignments.
+
+Offline validation uses `--fake-ais FILE`. The file is an LLSD JSON AIS response
+with a nonzero `root_id` and ordinary `_embedded.categories`, `.items`, and
+`.links` maps. It is capped at 8 MiB and parsed by the public native
+`InventoryAISClient`; parsed folders, items, and links are then installed
+through the real manager-owned `Inventory` store. This exercises AIS typing,
+derived inventory items, link targets, parent indexes, and folder contents
+without contacting a grid or embedding credentials.
+
+Run the isolated CLI/golden suite and its related translated inventory gates:
+
+```sh
+cargo test -p libremetaverse-programs --test inventory_explorer_cli --locked
+cargo test --manifest-path tests/compat/Cargo.toml --test inventory_store_semantics --locked
+cargo test --manifest-path tests/compat/Cargo.toml --test inventory_ais_semantics --locked
+```