AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Text To Binary Agent Guide

Agent guide for UTF-8 byte binary and hex encoding plus strict binary and hex decoding.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Text To Binary in the alexandrai-tools project.

Project overview

This guide covers src/tools/text-to-binary/index.ts. The tool encodes text with TextEncoder into UTF-8 bytes, outputs either eight-bit binary groups or uppercase two-digit hex groups with a caller-supplied separator, decodes whitespace-separated binary or hex groups, and uses fatal UTF-8 decoding to reject invalid byte sequences.

Primary source files

  • src/tools/text-to-binary/index.ts defines meta, BinMode, BinResult, textToBinary, binaryToText, and hexToText.
  • src/tools/text-to-binary/index.test.ts covers ASCII encoding, hex mode, empty input, custom separators, binary decoding, invalid binary groups, blank decode input, Unicode and emoji round trips, hex decoding, invalid hex, and hex round trips.
  • src/tools/text-to-binary/Body.astro owns browser controls.
  • src/tools/text-to-binary/i18n.ts owns localized copy.
  • src/lib/tools.ts registers metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Use TextEncoder for text input.
  • Output binary as eight-bit groups.
  • Output hex as uppercase two-character groups.
  • Return ok true with empty result for blank decode input.
  • Reject binary groups that are not exactly eight zero-or-one characters.
  • Reject hex groups that are not exactly two hex characters.
  • Return ok false when TextDecoder rejects invalid UTF-8 bytes.

Testing

Test ASCII, Unicode, emoji, empty input, custom separators, hex mode, binary decoding, hex decoding, invalid group length, invalid digits, invalid UTF-8 bytes, and UI mode switching.

PR checklist

  • npm test passes for text-to-binary.
  • Encoding, decoding, and failure behavior remain documented.
  • Browser-local processing and security limits stay clear in UI copy.
  • UI labels, metadata, and tests update together for behavior changes.