feat(xceadmin): add 'config dump' command and size-string thresholds

Adds `xceadmin config dump CLUSTER_BIN_PATH`, the reverse of `config
build` -- decodes a serialized ClusterConfig back to human-readable text
so a built config can be inspected without a throwaway pycapnp script.
Motivated directly by how bug-1556 (hosts.yaml's max_slot: -1 auto-detect
sentinel silently becoming mxj=0) was actually found: by hand-decoding a
live cluster.bin. The dump renders the same sentinel as
"max_slot=-1 (auto-detect from CPU count)", not the raw uint32.

Also adds parse_size_or_number() to xcecommon.mapping so a queue/host's
sched_stop threshold on a byte-valued resource (maxmem/mem/tmp/maxswap/
maxtmp) can be written as a human-friendly size string ("500MB", "2GB")
instead of a raw byte count; a plain number still passes through
unchanged for non-byte resources like load averages. hosts.schema.json
and queues.schema.json's sched_stop schema gains a matching SizeOrNumber
type. dump_cluster_config() humanizes the same byte-valued thresholds
back on the way out (_format_bytes_human).

New ClusterBinFileError covers every local cluster.bin read/decode
failure mode without letting a raw OSError/capnp.KjException escape the
CLI. RESOURCE_VALTYPE/RESOURCE_ORDTYPE/RESOURCE_FLAG_* made public in
mapping.py so dump_cluster_config can reuse the same int<->name tables
build_cluster_config already uses, keeping both directions in sync by
construction.

256 xceadmin tests pass (incl. new test_config_dump.py and the
parse_size_or_number/SizeOrNumber cases in test_mapping.py/test_cli.py),
verified via `xce-build.sh xceadmin`'s full pinned out-of-tree install
+ pytest run before this commit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/xceadmin/tests/test_config_dump.py

@@ -0,0 +1,128 @@
+"""Tests for ``xceadmin.build.dump_cluster_config`` -- the reverse of
+``build_cluster_config`` (decode a ``cluster.bin`` back to human-readable
+text). Uses the same ``tests/fixtures/full`` real-config fixture as
+test_config_build.py rather than a second golden text fixture: the
+assertions below check for specific substrings (mirrors
+test_scheduler.py's ``dump()`` test style), not a byte-exact text match,
+so formatting can evolve without a brittle golden file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import yaml
+
+from xcecommon.errors import ClusterBinFileError
+from xceadmin import build
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+@pytest.fixture
+def full_cluster_bin(tmp_path):
+    data = build.build_cluster_config(str(FIXTURES_DIR / "full" / "configs"))
+    path = tmp_path / "cluster.bin"
+    path.write_bytes(data)
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Section content
+# ---------------------------------------------------------------------------
+
+
+def test_dump_lists_cluster_scalars(full_cluster_bin):
+    text = build.dump_cluster_config(str(full_cluster_bin))
+    assert "=== ClusterConfig ===" in text
+    assert "clusterName:" in text
+    assert "heartbeatInterval:" in text
+
+
+def test_dump_lists_each_resource_with_decoded_type_and_order(full_cluster_bin):
+    text = build.dump_cluster_config(str(full_cluster_bin))
+    assert "=== resources (" in text
+    # "mem" is numeric/decrease/not consumable -- valtype/ordtype/flags int
+    # codes must render back to their YAML names, not raw ints.
+    assert "name=mem type=numeric order=decrease" in text
+    assert "consumable=False" in text
+
+
+def test_dump_renders_mxj_auto_detect_sentinel_not_raw_uint32(full_cluster_bin):
+    """The exact bug that motivated this feature: hosts.yaml's `default`
+    host has `max_slot: -1`, which wire-encodes as HOSTCONFIG_MXJ_AUTO_DETECT
+    (0xFFFFFFFF). The dump must show the human meaning, not the raw UInt32.
+    """
+    text = build.dump_cluster_config(str(full_cluster_bin))
+    assert "=== host: default ===" in text
+    assert "max_slot=-1 (auto-detect from CPU count)" in text
+    # worker2 has an explicit max_slot: 256 -- shown as a plain number.
+    assert "=== host: worker2 ===" in text
+    assert "max_slot=256" in text
+
+
+def test_dump_lists_queues_groups_scalers_and_limits(full_cluster_bin):
+    text = build.dump_cluster_config(str(full_cluster_bin))
+    assert "=== queues (" in text
+    assert "=== ugroups (" in text
+    assert "=== hgroups (" in text
+    assert "=== hproviders (" in text
+    assert "=== limits (" in text
+    assert "=== limit: ug1_slots ===" in text
+
+
+def test_dump_output_ends_with_trailing_newline(full_cluster_bin):
+    text = build.dump_cluster_config(str(full_cluster_bin))
+    assert text.endswith("\n")
+    assert not text.endswith("\n\n")
+
+
+def test_dump_humanizes_byte_valued_threshold(tmp_path):
+    """A host's sched_stop threshold on a byte-valued resource (maxmem) is
+    shown as a human-readable size, not a raw float byte count -- mirrors
+    the mem/tmp/maxswap/maxtmp/maxmem unit-consistency work this session.
+    """
+    (tmp_path / "hosts.yaml").write_text(
+        yaml.safe_dump(
+            {
+                "hosts": [
+                    {
+                        "hostname": "h1",
+                        "sched_stop": [{"resname": "maxmem", "sched": "500MB", "stop": "1GB"}],
+                    }
+                ]
+            }
+        )
+    )
+    data = build.build_cluster_config(str(tmp_path))
+    bin_path = tmp_path / "cluster.bin"
+    bin_path.write_bytes(data)
+
+    text = build.dump_cluster_config(str(bin_path))
+    assert "threshold: name=maxmem sched=500.00 MB stop=1.00 GB" in text
+
+
+# ---------------------------------------------------------------------------
+# Error handling
+# ---------------------------------------------------------------------------
+
+
+def test_dump_missing_file_raises_cluster_bin_file_error(tmp_path):
+    missing = tmp_path / "does-not-exist.bin"
+    with pytest.raises(ClusterBinFileError):
+        build.dump_cluster_config(str(missing))
+
+
+def test_dump_empty_file_raises_cluster_bin_file_error(tmp_path):
+    empty = tmp_path / "empty.bin"
+    empty.write_bytes(b"")
+    with pytest.raises(ClusterBinFileError):
+        build.dump_cluster_config(str(empty))
+
+
+def test_dump_garbage_bytes_raises_cluster_bin_file_error_not_crash(tmp_path):
+    garbage = tmp_path / "garbage.bin"
+    garbage.write_bytes(b"not a cluster config, just noise")
+    with pytest.raises(ClusterBinFileError):
+        build.dump_cluster_config(str(garbage))