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

The C FFI CLI now understands the container, dogfooding the FFI: pb_crc32 (now
declared in the public header), pb_encode, pb_decode. Adds shared
src/container_json.h (pure, transport-resistant flat-JSON helpers — canonicalize,
get-string, escape, basename), reused by the standalone C next. test-container-ffi
runs the parameterized guard (round-trip + self-verify + transport-resistance).

Author: pmarreck

.dirtree-state

@@ -3,6 +3,7 @@ ver=1.2
 annotate=[
 	PLAN.md = Issue #1 plan: decode workflow + printable-binary-file.json container
 	docs/plans/2026-06-26-printable-binary-file-container-design.md = Design spec: printable-binary-file.json container + web decode workflow (issue #1)
+	src/container_json.h = Shared pure transport-resistant flat-JSON helpers for the .pbf.json container (C FFI + standalone C)
 	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)

flake.nix

@@ -364,6 +364,20 @@
             installPhase = "mkdir -p $out && touch $out/passed";
           };
 
+          # Container (.pbf.json) for the C FFI CLI — dogfoods the FFI (pb_crc32 etc).
+          test-container-ffi = pkgs.stdenv.mkDerivation {
+            name = "test-container-ffi";
+            src = ./.;
+            nativeBuildInputs = with pkgs; [ zig clang ];
+            buildPhase = ''
+              export HOME=$TMPDIR
+              zig build
+              clang -O2 -I. -o pb-ffi src/printable_binary_ffi_main.c zig-out/lib/libprintable_binary.a
+              IMPLEMENTATION_TO_TEST=./pb-ffi 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 {

src/container_json.h

@@ -0,0 +1,81 @@
+/*
+ * container_json.h — pure, transport-resistant flat-JSON helpers for the
+ * printable-binary-file.json container (issue #1). Shared by the C FFI CLI and
+ * the standalone C CLI. No encode/decode/crc32 here (each caller supplies those
+ * via its own path); just the string handling. The `data` value is read to its
+ * closing quote regardless of whitespace a transport injected inside it, then
+ * canonicalized — the same natural transport-resistance as raw printable-binary.
+ */
+#ifndef CONTAINER_JSON_H
+#define CONTAINER_JSON_H
+
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* Strip transport whitespace (space/tab/CR/LF). malloc'd result (caller frees);
+ * *out_len set. Clean payloads (no literal whitespace) are unchanged. */
+static char *cj_canonical(const char *data, size_t len, size_t *out_len) {
+    char *out = (char *)malloc(len ? len : 1);
+    if (!out) { *out_len = 0; return NULL; }
+    size_t n = 0;
+    for (size_t i = 0; i < len; i++) {
+        char c = data[i];
+        if (c != ' ' && c != '\t' && c != '\r' && c != '\n') out[n++] = c;
+    }
+    *out_len = n;
+    return out;
+}
+
+/* Raw string value of "key" in a flat JSON object: pointer into `json` (not
+ * NUL-terminated), *out_len set; NULL if absent. Whitespace-tolerant. */
+static const char *cj_get_string(const char *json, size_t json_len, const char *key, size_t *out_len) {
+    char needle[80];
+    int kl = snprintf(needle, sizeof needle, "\"%s\"", key);
+    if (kl <= 0 || (size_t)kl >= sizeof needle) return NULL;
+    const char *p = NULL;
+    const char *end = json + json_len;
+    for (size_t i = 0; (size_t)kl <= json_len && i <= json_len - (size_t)kl; i++) {
+        if (memcmp(json + i, needle, (size_t)kl) == 0) { p = json + i + (size_t)kl; break; }
+    }
+    if (!p) return NULL;
+    while (p < end && (*p == ' ' || *p == '\t' || *p == '\r' || *p == '\n' || *p == ':')) p++;
+    if (p >= end || *p != '"') return NULL;
+    p++;
+    const char *start = p;
+    while (p < end) {
+        if (*p == '\\') { p += 2; continue; }
+        if (*p == '"') break;
+        p++;
+    }
+    if (p >= end) return NULL;
+    *out_len = (size_t)(p - start);
+    return start;
+}
+
+/* Write `s` JSON-escaped to `fp`. */
+static void cj_fputs_escaped(FILE *fp, const char *s, size_t len) {
+    for (size_t i = 0; i < len; i++) {
+        unsigned char c = (unsigned char)s[i];
+        switch (c) {
+            case '"':  fputs("\\\"", fp); break;
+            case '\\': fputs("\\\\", fp); break;
+            case '\n': fputs("\\n", fp);  break;
+            case '\r': fputs("\\r", fp);  break;
+            case '\t': fputs("\\t", fp);  break;
+            default:   fputc(c, fp);      break;
+        }
+    }
+}
+
+/* Basename after the last '/' or '\\' (pointer into `path`). */
+static const char *cj_basename(const char *path) {
+    const char *b = path;
+    for (const char *p = path; *p; p++) {
+        if (*p == '/' || *p == '\\') b = p + 1;
+    }
+    return b;
+}
+
+#endif /* CONTAINER_JSON_H */

src/printable_binary.h

@@ -137,6 +137,13 @@ typedef struct {
  */
 void pb_free(char *ptr, size_t len);
 
+/**
+ * CRC-32/ISO-HDLC of `input_len` bytes at `input` (the zip/gzip/png CRC); used
+ * for printable-binary-file.json container integrity. NULL or zero-length input
+ * yields the CRC of empty input (0).
+ */
+uint32_t pb_crc32(const char *input, size_t input_len);
+
 /**
  * Encode binary data to printable UTF-8.
  * Caller must call pb_free() on result.data when done.

src/printable_binary_ffi_main.c

@@ -20,6 +20,7 @@
 #include <errno.h>
 
 #include "printable_binary.h"
+#include "container_json.h"
 
 /* Program options */
 typedef struct {
@@ -42,6 +43,7 @@ typedef struct {
     int64_t range_start;
     int64_t range_end;
     bool no_double_encode_check;
+    bool container_mode;
 } options_t;
 
 static bool env_var_truthy(const char *value) {
@@ -63,6 +65,8 @@ static void print_usage(const char *name) {
     fprintf(stderr, "  -d, --decode       Decode mode (default is encode mode)\n");
     fprintf(stderr, "  -p, --passthrough  Pass input to stdout unchanged, send encoded data to stderr\n");
     fprintf(stderr, "  -X, --hexlike      Hexlike mode (passthrough ASCII as-is, other bytes as \xce\x9f\xcf\x87-prefixed hex)\n");
+    fprintf(stderr, "  -C, --container    Container mode: encode a file to a self-verifying .pbf.json\n");
+    fprintf(stderr, "                     (keeps filename + crc32). With -d, decode a container back.\n");
     fprintf(stderr, "\nEncode options (preserve literal characters instead of encoding):\n");
     fprintf(stderr, "  -s, --spaces       Preserve literal spaces\n");
     fprintf(stderr, "  -t, --tabs         Preserve literal tabs\n");
@@ -235,6 +239,8 @@ static options_t parse_options(int argc, char *argv[]) {
                 opts.passthrough_mode = true;
             } else if (strcmp(name, "hexlike") == 0) {
                 opts.hexlike_mode = true;
+            } else if (strcmp(name, "container") == 0) {
+                opts.container_mode = true;
             } else if (strcmp(name, "spaces") == 0) {
                 opts.spaces_mode = true;
             } else if (strcmp(name, "tabs") == 0) {
@@ -325,6 +331,7 @@ static options_t parse_options(int argc, char *argv[]) {
                     case 'd': opts.decode_mode = true; break;
                     case 'p': opts.passthrough_mode = true; break;
                     case 'X': opts.hexlike_mode = true; break;
+                    case 'C': opts.container_mode = true; break;
                     case 's': opts.spaces_mode = true; break;
                     case 't': opts.tabs_mode = true; break;
                     case 'n': opts.crlf_mode = true; break;
@@ -523,6 +530,54 @@ int main(int argc, char *argv[]) {
         input_len = range.length;
     }
 
+    if (opts.container_mode) {
+        if (opts.decode_mode) {
+            size_t dlen;
+            const char *draw = cj_get_string(input, input_len, "data", &dlen);
+            if (!draw) { fprintf(stderr, "Error: not a printable-binary-file container (missing 'data')\n"); free(input); return 1; }
+            size_t clen;
+            char *clean = cj_canonical(draw, dlen, &clen);
+            size_t celen;
+            const char *ce = cj_get_string(input, input_len, "crc32_encoded", &celen);
+            if (ce) {
+                char hx[9]; snprintf(hx, 9, "%08x", pb_crc32(clean, clen));
+                if (celen != 8 || memcmp(hx, ce, 8) != 0) { free(clean); free(input); fprintf(stderr, "Error: container crc32_encoded mismatch (data corrupted)\n"); return 1; }
+            }
+            pb_ffi_result_t dr = pb_decode(clean, clen, 0);
+            free(clean);
+            if (dr.error_code) { free(input); fprintf(stderr, "Error: container decode failed\n"); return 1; }
+            size_t colen;
+            const char *co = cj_get_string(input, input_len, "crc32", &colen);
+            if (co) {
+                char hx[9]; snprintf(hx, 9, "%08x", pb_crc32(dr.data, dr.len));
+                if (colen != 8 || memcmp(hx, co, 8) != 0) { pb_free(dr.data, dr.len); free(input); fprintf(stderr, "Error: container crc32 mismatch (decoded data corrupted)\n"); return 1; }
+            }
+            fwrite(dr.data, 1, dr.len, stdout);
+            pb_free(dr.data, dr.len);
+            free(input);
+            return 0;
+        } else {
+            pb_ffi_result_t er = pb_encode(input, input_len, 0, NULL, 0);
+            if (er.error_code) { free(input); fprintf(stderr, "Error: container encode failed\n"); return 1; }
+            size_t clen;
+            char *clean = cj_canonical(er.data, er.len, &clen);
+            char crc_orig[9], crc_enc[9];
+            snprintf(crc_orig, 9, "%08x", pb_crc32(input, input_len));
+            snprintf(crc_enc, 9, "%08x", pb_crc32(clean, clen));
+            free(clean);
+            const char *fname = (opts.input_file && strcmp(opts.input_file, "-") != 0) ? cj_basename(opts.input_file) : "";
+            printf("{\n  \"format\": \"printable-binary-file\",\n  \"version\": 1,\n  \"filename\": \"");
+            cj_fputs_escaped(stdout, fname, strlen(fname));
+            printf("\",\n  \"byte_length\": %zu,\n  \"crc32\": \"%s\",\n  \"crc32_encoded\": \"%s\",\n  \"data\": \"", input_len, crc_orig, crc_enc);
+            fwrite(er.data, 1, er.len, stdout);
+            printf("\"\n}\n");
+            pb_free(er.data, er.len);
+            free(input);
+            return 0;
+        }
+    }
+
+
     if (opts.decode_mode) {
         if (opts.passthrough_mode) {
             fprintf(stderr, "Warning: --passthrough ignored in decode mode\n");