AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools String Escape Agent Guide

Agent guide for JSON, JavaScript, HTML, and URL escaping and unescaping behavior.

AGENTS.md

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

Project overview

This guide covers src/tools/string-escape/index.ts. The tool escapes URL mode with encodeURIComponent, escapes HTML entities in a fixed order, escapes JSON and JavaScript control characters manually, adds single-quote escaping only in JavaScript mode, and unescapes URL, HTML, JSON, and JavaScript forms with best-effort behavior.

Primary source files

  • src/tools/string-escape/index.ts defines meta, EscapeMode, escapeFor, and unescapeFor.
  • src/tools/string-escape/index.test.ts covers JSON special characters, HTML entities, URL encoding, and JSON, HTML, and URL round trips.
  • src/tools/string-escape/Body.astro owns browser controls.
  • src/tools/string-escape/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 encodeURIComponent for URL escaping.
  • Return original text if URL decoding throws.
  • Escape ampersand before other HTML entities.
  • Escape single quote to numeric HTML entity.
  • Escape JSON and JavaScript control characters manually.
  • Escape single quote only in JavaScript mode.
  • Unescape supported JSON and JavaScript escape sequences with the existing regex.

Testing

Test JSON escapes, JavaScript single quotes, control characters, unicode escapes, HTML entity order, URL decode failures, round trips, unsupported entities, empty input, and UI copy for best-effort unescape.

PR checklist

  • npm test passes for string-escape.
  • 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.