Summary

Implements efficient binary format encoding/decoding for multi-file support, completing issue #37.

Changes

New Files

• lib/binary.ts: Complete binary format implementation with:

  • encodeFiles() - Encodes multiple files into compact binary format
  • decodeFiles() - Decodes binary data back to files with validation
  • validateBinaryFormat() - Quick format validation without full decode
  • extractHeader() - Reads header information
  • Helper functions for byte conversions

• lib/binary.test.ts: Comprehensive test suite with 35 tests

Binary Format Structure

[4 bytes: Magic "GPST" (0x47505354)]
[1 byte: Version (1)]
[2 bytes: File count]
[4 bytes: Total size]
For each file:
  [2 bytes: Filename length]
  [N bytes: Filename (UTF-8)]
  [4 bytes: Content length]
  [N bytes: Content (UTF-8)]
  [1 byte: Language length]
  [N bytes: Language (UTF-8, optional)]

Error Handling Improvements

• Removed duplicate BinaryFormatError (kept InvalidBinaryFormatError)
• Removed generic ValidationError in favor of specific errors:
  • BadRequestError for general validation failures
  • FileTooLargeError for individual file size violations
  • TooManyFilesError for file count violations
  • PayloadTooLargeError for total size violations

Size Limits Enforced

• Max file size: 500KB per file
• Max total size: 5MB
• Max file count: 20 files
• Max filename length: 255 characters
• Max language identifier: 50 characters

Test Coverage

All 35 tests passing, covering:

• ✅ Normal operations (single/multiple files)
• ✅ Edge cases (empty files, Unicode, special characters)
• ✅ Error conditions and validation
• ✅ Size limit enforcement
• ✅ Format corruption detection
• ✅ Round-trip data integrity

Test Plan

• Unit tests pass
• Handles Unicode filenames and content correctly
• Enforces all size limits
• Detects and rejects corrupted data
• Efficient packing (minimal overhead)

Closes #37

🤖 Generated with Claude Code