feat: add list API, CLI subcommand, and WASM binding

Author: theaddonn

cli/src/args.rs

@@ -38,4 +38,11 @@ pub enum CliSubcommand {
         #[arg(long)]
         delete_source: bool,
     },
+    #[command(about = "List entry names in a .brarchive file")]
+    List {
+        path: PathBuf,
+        /// Given a directory, list entries in all .brarchive files under __brarchive/
+        #[arg(short, long)]
+        recursive: bool,
+    },
 }

cli/src/main.rs

@@ -34,6 +34,18 @@ fn main() {
                 info!("Successfully encoded archive in {}!", humantime::format_duration(start_time.elapsed()));
             }
         }
+        CliSubcommand::List { path, recursive } => {
+            if recursive {
+                let archive_root = path.join("__brarchive");
+                if !archive_root.exists() {
+                    error!("No __brarchive/ directory found in \"{}\"", path.display());
+                    exit(1);
+                }
+                list_recursive(&archive_root, &archive_root);
+            } else {
+                list_single(&path);
+            }
+        }
         CliSubcommand::Decode { path, out, recursive, delete_source } => {
             let start_time = Instant::now();
 
@@ -265,6 +277,38 @@ fn decode_recursive(archive_root: &Path, current: &Path, out_root: &Path, delete
     }
 }
 
+fn list_single(path: &Path) {
+    let data = fs::read(path).unwrap_or_else(|err| {
+        error!("Failed to read \"{}\": {}", path.display(), err);
+        exit(1);
+    });
+    let names = brarchive::list(&data).unwrap_or_else(|err| {
+        error!("Failed to list \"{}\": {}", path.display(), err);
+        exit(1);
+    });
+    for name in names {
+        println!("{}", name);
+    }
+}
+
+fn list_recursive(archive_root: &Path, current: &Path) {
+    let read_dir = fs::read_dir(current).unwrap_or_else(|err| {
+        error!("Failed to read \"{}\": {}", current.display(), err);
+        exit(1);
+    });
+    for entry in read_dir {
+        let entry = entry.unwrap_or_else(|err| { error!("{}", err); exit(1); });
+        let p = entry.path();
+        if p.is_dir() {
+            list_recursive(archive_root, &p);
+        } else if p.is_file() && p.extension().and_then(OsStr::to_str) == Some("brarchive") {
+            let relative = p.strip_prefix(archive_root).unwrap_or(&p);
+            println!("{}:", relative.display());
+            list_single(&p);
+        }
+    }
+}
+
 fn extract_file_name(path: &Path) -> Option<PathBuf> {
     path.file_stem().and_then(OsStr::to_str).map(PathBuf::from)
 }

lib/src/lib.rs

@@ -97,6 +97,15 @@ where
     Ok(buf)
 }
 
+/// List entry names in a .brarchive file without reading content.
+pub fn list(data: &[u8]) -> Result<Vec<String>, BrArchiveError> {
+    let mut buf = Cursor::new(data);
+    let header = v1::read_header(&mut buf)?;
+    (0..header.entries)
+        .map(|_| v1::read_entry_descriptor(&mut buf).map(|e| e.name.to_string()))
+        .collect()
+}
+
 /// Deserialize a .brarchive file into any collection constructible from (String, String) pairs.
 ///
 /// Use a type annotation to select the output type:

lib/tests/api.rs

@@ -67,3 +67,36 @@ fn serialize_with_no_dedup_matches_serialize() {
     let b = brarchive::serialize_with(data, SerializeOptions { dedup: false }).unwrap();
     assert_eq!(a, b);
 }
+
+#[test]
+fn list_returns_entry_names() {
+    let bytes = brarchive::serialize([
+        ("a.json", "1"),
+        ("b.json", "2"),
+        ("c.json", "3"),
+    ]).unwrap();
+    let names = brarchive::list(&bytes).unwrap();
+    assert_eq!(names, vec!["a.json", "b.json", "c.json"]);
+}
+
+#[test]
+fn list_empty_archive() {
+    let bytes = brarchive::serialize::<Vec<(&str, &str)>, _, _>(vec![]).unwrap();
+    let names = brarchive::list(&bytes).unwrap();
+    assert!(names.is_empty());
+}
+
+#[test]
+fn list_does_not_require_reading_content() {
+    // list should work even when content bytes are not present (header + descriptors only).
+    // Verify that list() and deserialize() agree on names.
+    let data = vec![
+        ("x.json".to_string(), "hello".to_string()),
+        ("y.json".to_string(), "world".to_string()),
+    ];
+    let bytes = brarchive::serialize(data).unwrap();
+    let names = brarchive::list(&bytes).unwrap();
+    let map: std::collections::BTreeMap<String, String> = brarchive::deserialize(&bytes).unwrap();
+    let map_keys: Vec<&str> = map.keys().map(String::as_str).collect();
+    assert_eq!(names, map_keys);
+}

wasm/src/lib.rs

@@ -27,6 +27,15 @@ pub fn serialize_with_options(entries: JsValue, dedup: bool) -> Result<Uint8Arra
     Ok(Uint8Array::from(bytes.as_slice()))
 }
 
+/// List entry names in a .brarchive file without reading content. Returns a `string[]`.
+#[wasm_bindgen]
+pub fn list(data: &[u8]) -> Result<JsValue, JsError> {
+    let names = brarchive::list(data)
+        .map_err(|e| JsError::new(&e.to_string()))?;
+    serde_wasm_bindgen::to_value(&names)
+        .map_err(|e| JsError::new(&e.to_string()))
+}
+
 /// Deserialize .brarchive bytes into a plain JS object `{ [key: string]: string }`.
 #[wasm_bindgen]
 pub fn deserialize(data: &[u8]) -> Result<JsValue, JsError> {