AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Base64 Agent Guide

Agent guide for UTF-8 Base64 encoding, URL-safe Base64, and structured decode errors.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Base64 in the alexandrai-tools project.

Project overview

This guide covers src/tools/base64/index.ts. The tool encodes text through TextEncoder before btoa, optionally emits URL-safe Base64 without padding, normalizes URL-safe input before decode, restores padding when possible, decodes bytes through TextDecoder with fatal UTF-8 handling, and returns structured DecodeResult errors.

Primary source files

  • src/tools/base64/index.ts defines meta, encodeBase64, DecodeResult, and decodeBase64.
  • src/tools/base64/index.test.ts covers ASCII, Unicode round trips, URL-safe output, invalid input, empty input, whitespace input, and padding.
  • src/tools/base64/Body.astro owns the browser controls.
  • src/tools/base64/i18n.ts owns localized copy.
  • src/lib/tools.ts auto-discovers the tool metadata.

Setup commands

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

Change rules

  • Keep TextEncoder and TextDecoder in the pure logic path so non-ASCII input round-trips correctly.
  • Keep URL-safe output free of standard plus, slash, and padding characters.
  • Return ok true with empty output for empty or whitespace-only decode input.
  • Return ok false with an Invalid Base64 message for malformed input instead of throwing.
  • Do not add server decoding or upload behavior; this utility should stay browser-local.
  • If binary output is added later, keep text and bytes APIs separate.
  • Preserve padding restoration for URL-safe input with missing padding.

Testing

Test ASCII encode, Unicode round trip, URL-safe encode, URL-safe decode without padding, invalid alphabet input, invalid UTF-8 bytes, empty input, whitespace-only input, and standard padded values.

PR checklist

  • npm test passes for base64.
  • Unicode text round-trips through encode and decode.
  • Malformed decode input returns a structured error.
  • No generated guide contains private encoded payload examples.