feat(node-cli): -C/--container — emit & consume .pbf.json (issue #1)

The Node CLI now understands the container: `-C <file>` emits a self-verifying
.pbf.json (filename + modified_ms + created_ms + mode from stat, plus crc32);
`-d -C <container>` restores the original bytes (self-verify; corrupt -> nonzero
exit). Reuses the JS lib's encodeToContainer/decodeText.

Adds test/test_container — a parameterized (IMPLEMENTATION_TO_TEST) CLI round-trip
+ non-vacuous self-verify oracle — wired into CI as test-container-node. The same
script will exercise the Zig/C/Lua CLIs as they gain -C.

Author: pmarreck

.dirtree-state

@@ -5,5 +5,6 @@ annotate=[
 	docs/plans/2026-06-26-printable-binary-file-container-design.md = Design spec: printable-binary-file.json container + web decode workflow (issue #1)
 	src/zig/ffi.zig = C ABI (FFI) export surface: all 12 pb_* C functions; root of libprintable_binary.a; keeps C symbols OUT of the importable printable_binary module so static (musl) consumers don't collide
 	test/module_consumer.zig = Test fixture: minimal downstream importer of the printable_binary Zig module (mirrors how difz/blip consume it) for the FFI-symbol-leak test
+	test/test_container = Container (.pbf.json) CLI round-trip + self-verify test, parameterized by IMPLEMENTATION_TO_TEST (issue #1)
 	test/test_module_no_ffi_symbols = Regression test (nm oracle): importing the module must emit 0 pb_* symbols while the FFI static lib keeps all 12 — guards the difz-blocking duplicate-symbol bug
 ]

bin/printable-binary-node.js

@@ -41,6 +41,9 @@ Encoding modes:
                    shown as uppercase hex runs prefixed by \u039F\u03C7 (Greek Omicron+Chi,
                    NOT ASCII 0x \u2014 beware when copying hex for other purposes).
                    Use with -d to decode hexlike-encoded data back to binary.
+  -C, --container  Container mode: encode a file to a self-verifying .pbf.json
+                   (keeps filename, dates, perms + crc32). Use with -d to decode
+                   a .pbf.json container back to the original file.
 
 Range options (select byte range from input before processing):
   --range X-Y              Byte range, 0-indexed inclusive (e.g., --range 0-9)
@@ -152,6 +155,7 @@ function parseArgs(argv) {
   let crlfMode = false;
   let preserveChars = '';
   let hexlikeMode = false;
+  let containerMode = false;
 
   const setMappingsFormat = (mode) => {
     if (mappingsFormat && mappingsFormat !== mode) {
@@ -207,6 +211,8 @@ function parseArgs(argv) {
       preserveChars = arg.slice(11);
     } else if (arg === '-X' || arg === '--hexlike') {
       hexlikeMode = true;
+    } else if (arg === '-C' || arg === '--container') {
+      containerMode = true;
     } else if (arg === '--no-double-encode-check') {
       noDoubleEncodeCheck = true;
     } else if (arg === '--range') {
@@ -258,6 +264,7 @@ function parseArgs(argv) {
           case 'p': passthrough = true; break;
           case 'S': stripWhitespace = true; break;
           case 'X': hexlikeMode = true; break;
+          case 'C': containerMode = true; break;
           default:
             process.stderr.write(`Error: Unknown option -${ch}\n`);
             printUsage();
@@ -287,7 +294,7 @@ function parseArgs(argv) {
     }
   }
 
-  return { decodeMode, formatSpec, filePath, mappingsFormat, passthrough, spacesMode, stripWhitespace, tabsMode, crlfMode, preserveChars, rangeStart, rangeEnd, noDoubleEncodeCheck, hexlikeMode };
+  return { decodeMode, formatSpec, filePath, mappingsFormat, passthrough, spacesMode, stripWhitespace, tabsMode, crlfMode, preserveChars, rangeStart, rangeEnd, noDoubleEncodeCheck, hexlikeMode, containerMode };
 }
 
 async function readInput(filePath) {
@@ -314,7 +321,7 @@ function stats(msg) {
 }
 
 async function main() {
-  const { decodeMode, formatSpec, filePath, mappingsFormat, passthrough, spacesMode, stripWhitespace, tabsMode, crlfMode, preserveChars, rangeStart, rangeEnd, noDoubleEncodeCheck, hexlikeMode } = parseArgs(process.argv.slice(2));
+  const { decodeMode, formatSpec, filePath, mappingsFormat, passthrough, spacesMode, stripWhitespace, tabsMode, crlfMode, preserveChars, rangeStart, rangeEnd, noDoubleEncodeCheck, hexlikeMode, containerMode } = parseArgs(process.argv.slice(2));
   const pb = new PrintableBinary();
 
   try {
@@ -353,6 +360,30 @@ async function main() {
       }
     }
 
+    if (containerMode) {
+      if (decodeMode) {
+        const res = pb.decodeText(input.toString('utf8'));
+        stats(`Decoded ${res.kind} container${res.filename && res.filename !== 'decoded.bin' ? ' (' + res.filename + ')' : ''}: ${res.bytes.length} bytes`);
+        process.stdout.write(Buffer.from(res.bytes));
+      } else {
+        const meta = {};
+        if (filePath) {
+          meta.filename = filePath.split(/[\\/]/).pop();
+          try {
+            const st = fs.statSync(filePath);
+            meta.modified_ms = Math.round(st.mtimeMs);
+            if (st.birthtimeMs && st.birthtimeMs > 0) meta.created_ms = Math.round(st.birthtimeMs);
+            meta.mode = '0' + (st.mode & 0o777).toString(8);
+          } catch (_e) { /* metadata is best-effort */ }
+        }
+        const container = pb.encodeToContainer(new Uint8Array(input), meta);
+        stats(`Encoded ${input.length} bytes -> .pbf.json container (crc32 ${container.crc32})`);
+        process.stdout.write(JSON.stringify(container, null, 2) + '\n');
+      }
+      return;
+    }
+
+
     if (decodeMode) {
       if (passthrough) {
         process.stderr.write('Warning: --passthrough ignored in decode mode\n');

flake.nix

@@ -323,6 +323,20 @@
             installPhase = "mkdir -p $out && touch $out/passed";
           };
 
+          # Container (.pbf.json) CLI round-trip + self-verify, issue #1. Parameterized
+          # by IMPLEMENTATION_TO_TEST; one check per impl as they gain -C/--container.
+          test-container-node = pkgs.stdenv.mkDerivation {
+            name = "test-container-node";
+            src = ./.;
+            nativeBuildInputs = with pkgs; [ nodejs_24 ];
+            buildPhase = ''
+              export HOME=$TMPDIR
+              patchShebangs bin/printable-binary-node.js
+              IMPLEMENTATION_TO_TEST=./bin/printable-binary-node.js bash ./test/test_container
+            '';
+            installPhase = "mkdir -p $out && touch $out/passed";
+          };
+
           # Dogfood the C FFI boundary: build the C FFI CLI against the Zig static
           # lib and round-trip through it (encode/decode + hexlike).
           test-ffi-cli = pkgs.stdenv.mkDerivation {

test/test_container

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Container (.pbf.json) CLI round-trip + self-verify test, parameterized by
+# IMPLEMENTATION_TO_TEST so every printable-binary executable is exercised the
+# same way as it gains `-C`/`--container` support. (issue #1)
+#
+# MFIC: inverse-pair oracle (decode(encode(file)) == file, byte-identical) plus a
+# non-vacuous self-verify (a corrupted container MUST be rejected with nonzero exit).
+set -u
+IMPL="${IMPLEMENTATION_TO_TEST:-./bin/printable-binary-node.js}"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+pass=0; fail=0
+ok()  { echo "  ✓ $1"; pass=$((pass+1)); }
+bad() { echo "  ✗ $1"; fail=$((fail+1)); }
+
+echo "=== container CLI test: $IMPL ==="
+
+# 1. a file with known, binary-ish bytes
+printf 'Hello\x00\x01\xff binary\n{not json}\n' > "$TMP/orig.bin"
+
+# 2. encode -> container
+if "$IMPL" -C "$TMP/orig.bin" > "$TMP/orig.pbf.json" 2>"$TMP/enc.err"; then ok "encode -C exits 0"; else bad "encode -C exits 0"; echo "    $(cat "$TMP/enc.err")"; fi
+
+# 3. container shape
+grep -q '"format"' "$TMP/orig.pbf.json" 2>/dev/null && grep -q 'printable-binary-file' "$TMP/orig.pbf.json" && ok "container has format=printable-binary-file" || bad "container has format=printable-binary-file"
+grep -q '"filename"' "$TMP/orig.pbf.json" 2>/dev/null && grep -q 'orig.bin' "$TMP/orig.pbf.json" && ok "container carries filename" || bad "container carries filename"
+grep -q '"crc32"' "$TMP/orig.pbf.json" 2>/dev/null && ok "container carries crc32" || bad "container carries crc32"
+
+# 4. decode -> original bytes
+if "$IMPL" -d -C "$TMP/orig.pbf.json" > "$TMP/restored.bin" 2>"$TMP/dec.err"; then ok "decode -d -C exits 0"; else bad "decode -d -C exits 0"; echo "    $(cat "$TMP/dec.err")"; fi
+if cmp -s "$TMP/orig.bin" "$TMP/restored.bin"; then ok "round-trip bytes identical"; else bad "round-trip bytes identical"; fi
+
+# 5. self-verify is non-vacuous: corrupt the data string -> decode MUST fail
+sed 's/\("data": *"\)/\1ZZZ/' "$TMP/orig.pbf.json" > "$TMP/corrupt.pbf.json"
+if "$IMPL" -d -C "$TMP/corrupt.pbf.json" > /dev/null 2>&1; then bad "corrupt container rejected (nonzero exit)"; else ok "corrupt container rejected (nonzero exit)"; fi
+
+echo "container CLI test [$IMPL]: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]