feat(ffi): expose hexlike through the C ABI (no more bypass-only feature)

Hexlike (-X) lived only in the Zig core and was reachable solely by importing
the core directly; the FFI CLI rejected -X entirely. Add pb_hexlike_encode,
pb_hexlike_decode, and pb_detect_hexlike exports (null-guarded, FFIResult-based,
matching the existing pb_* pattern) to the Zig core + printable_binary.h, and
wire -X/--hexlike into the FFI CLI so it routes through those exports.

Verified: Zig unit test (FFI hexlike roundtrip + detect + null safety) and an
end-to-end FFI-CLI build — 'Hi\xff! World' -> 'Hi ΟχFF2120 World' -> roundtrips.

Author: pmarreck

src/printable_binary.h

@@ -244,6 +244,34 @@ typedef struct {
  */
 pb_double_encode_info_t pb_detect_double_encode(const char *input, size_t input_len, float threshold);
 
+/* ============================================================================
+ * Hexlike API (passthrough ASCII stays as-is; other bytes -> Οχ-prefixed hex)
+ * ============================================================================ */
+
+/**
+ * Encode binary data to hexlike format. Caller must call pb_free() on result.data.
+ * @param input      Binary data (may be NULL only when input_len == 0)
+ * @param input_len  Length of input in bytes
+ * @param spaces     Non-zero to preserve literal spaces as passthrough
+ * @return           Result with hexlike-encoded data or error
+ */
+pb_ffi_result_t pb_hexlike_encode(const char *input, size_t input_len, int spaces);
+
+/**
+ * Decode hexlike text back to binary. Caller must call pb_free() on result.data.
+ * @param input      Hexlike-encoded text (may be NULL only when input_len == 0)
+ * @param input_len  Length of input in bytes
+ * @param spaces     Non-zero to treat literal spaces as data
+ * @return           Result with decoded data or error
+ */
+pb_ffi_result_t pb_hexlike_decode(const char *input, size_t input_len, int spaces);
+
+/**
+ * Detect whether input appears to be hexlike-encoded.
+ * @return 1 if hexlike, 0 otherwise (also 0 on NULL with input_len > 0)
+ */
+int pb_detect_hexlike(const char *input, size_t input_len);
+
 /* ============================================================================
  * C Implementation Only
  * ============================================================================ */

src/printable_binary_ffi_main.c

@@ -29,6 +29,7 @@ typedef struct {
     bool tabs_mode;
     bool crlf_mode;
     bool strip_whitespace;
+    bool hexlike_mode;
     bool format_mode;
     bool help_mode;
     int format_group;
@@ -61,6 +62,7 @@ static void print_usage(const char *name) {
     fprintf(stderr, "Options:\n");
     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, "\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");
@@ -230,6 +232,8 @@ static options_t parse_options(int argc, char *argv[]) {
                 opts.decode_mode = true;
             } else if (strcmp(name, "passthrough") == 0) {
                 opts.passthrough_mode = true;
+            } else if (strcmp(name, "hexlike") == 0) {
+                opts.hexlike_mode = true;
             } else if (strcmp(name, "spaces") == 0) {
                 opts.spaces_mode = true;
             } else if (strcmp(name, "tabs") == 0) {
@@ -319,6 +323,7 @@ static options_t parse_options(int argc, char *argv[]) {
                 switch (arg[j]) {
                     case 'd': opts.decode_mode = true; break;
                     case 'p': opts.passthrough_mode = true; break;
+                    case 'X': opts.hexlike_mode = true; break;
                     case 's': opts.spaces_mode = true; break;
                     case 't': opts.tabs_mode = true; break;
                     case 'n': opts.crlf_mode = true; break;
@@ -540,7 +545,9 @@ int main(int argc, char *argv[]) {
         if (opts.spaces_mode) flags |= PB_DECODE_SPACES_MODE;
         if (opts.strip_whitespace) flags |= PB_DECODE_STRIP_WS;
 
-        pb_ffi_result_t result = pb_decode(input, input_len, flags);
+        pb_ffi_result_t result = opts.hexlike_mode
+            ? pb_hexlike_decode(input, input_len, opts.spaces_mode ? 1 : 0)
+            : pb_decode(input, input_len, flags);
         if (result.error_code != 0 || !result.data) {
             fprintf(stderr, "Decode error\n");
             free(input);
@@ -578,8 +585,9 @@ int main(int argc, char *argv[]) {
         if (opts.crlf_mode) flags |= PB_ENCODE_PRESERVE_CRLF;
 
         size_t preserve_len = opts.preserve_chars ? strlen(opts.preserve_chars) : 0;
-        pb_ffi_result_t result = pb_encode(input, input_len, flags,
-                                           opts.preserve_chars, preserve_len);
+        pb_ffi_result_t result = opts.hexlike_mode
+            ? pb_hexlike_encode(input, input_len, opts.spaces_mode ? 1 : 0)
+            : pb_encode(input, input_len, flags, opts.preserve_chars, preserve_len);
         if (result.error_code != 0 || !result.data) {
             fprintf(stderr, "Encode error\n");
             free(input);

src/zig/printable_binary.zig

@@ -357,6 +357,37 @@ export fn pb_detect_double_encode(input: ?[*]const u8, input_len: usize, thresho
     return detectDoubleEncode(slice, threshold);
 }
 
+/// C ABI export for hexlike encoding. Caller must call pb_free() on result.data.
+export fn pb_hexlike_encode(input: ?[*]const u8, input_len: usize, spaces: c_int) callconv(.c) FFIResult {
+    if (input == null and input_len > 0) {
+        return FFIResult{ .data = null, .len = 0, .error_code = 1 };
+    }
+    const input_slice = if (input_len > 0) input.?[0..input_len] else &[_]u8{};
+    const result = hexlikeEncode(ffi_allocator, input_slice, .{ .spaces = spaces != 0 }) catch {
+        return FFIResult{ .data = null, .len = 0, .error_code = 1 };
+    };
+    return FFIResult{ .data = result.ptr, .len = result.len, .error_code = 0 };
+}
+
+/// C ABI export for hexlike decoding. Caller must call pb_free() on result.data.
+export fn pb_hexlike_decode(input: ?[*]const u8, input_len: usize, spaces: c_int) callconv(.c) FFIResult {
+    if (input == null and input_len > 0) {
+        return FFIResult{ .data = null, .len = 0, .error_code = 1 };
+    }
+    const input_slice = if (input_len > 0) input.?[0..input_len] else &[_]u8{};
+    const result = hexlikeDecode(ffi_allocator, input_slice, .{ .spaces = spaces != 0 }) catch {
+        return FFIResult{ .data = null, .len = 0, .error_code = 1 };
+    };
+    return FFIResult{ .data = result.data.ptr, .len = result.data.len, .error_code = 0 };
+}
+
+/// C ABI export for hexlike detection. Returns 1 if input appears hexlike, else 0.
+export fn pb_detect_hexlike(input: ?[*]const u8, input_len: usize) callconv(.c) c_int {
+    if (input == null and input_len > 0) return 0;
+    const input_slice = if (input_len > 0) input.?[0..input_len] else &[_]u8{};
+    return if (detectHexlike(input_slice)) 1 else 0;
+}
+
 /// Get UTF-8 sequence length from first byte
 pub fn utf8SeqLen(first_byte: u8) u3 {
     if (first_byte < 0x80) return 1;
@@ -1478,3 +1509,19 @@ test "parseGlyphLine: filters comments/blank, strips trailing comment, takes fir
     // CRLF tolerance
     try std.testing.expectEqualStrings("·", parseGlyphLine("·\r").?);
 }
+
+test "FFI: pb_hexlike_encode/decode roundtrip + detect + null safety" {
+    const input = "Hi\xff!";
+    const enc = pb_hexlike_encode(input.ptr, input.len, 0);
+    try std.testing.expect(enc.error_code == 0);
+    defer pb_free(enc.data, enc.len);
+    try std.testing.expect(pb_detect_hexlike(enc.data, enc.len) == 1);
+    const dec = pb_hexlike_decode(enc.data, enc.len, 0);
+    try std.testing.expect(dec.error_code == 0);
+    defer pb_free(dec.data, dec.len);
+    try std.testing.expectEqualStrings(input, dec.data.?[0..dec.len]);
+    // null safety
+    const bad = pb_hexlike_encode(null, 100, 0);
+    try std.testing.expect(bad.error_code != 0);
+    try std.testing.expect(pb_detect_hexlike(null, 100) == 0);
+}