AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Find and Replace in the alexandrai-tools project.

Project overview

This guide covers src/tools/find-and-replace/index.ts. The tool returns the original text unchanged when the find string is empty, escapes literal search text unless regex mode is selected, optionally wraps the pattern in word boundaries, applies global and optional case-insensitive flags, counts replacements, and returns structured regex errors.

Primary source files

• src/tools/find-and-replace/index.ts defines meta, FindReplaceOptions, FindReplaceResult, and findAndReplace.
• src/tools/find-and-replace/index.test.ts covers all occurrences, case-insensitive mode, whole-word mode, regex mode, invalid regex, empty find string, and delete replacement.
• src/tools/find-and-replace/Body.astro owns the browser text fields and options.
• src/tools/find-and-replace/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

• Return the original text and count zero when find is empty.
• Escape literal search text before creating a RegExp.
• Apply whole-word boundaries after choosing literal or regex mode.
• Use global replacement so all matches are counted.
• Catch invalid regex construction and return ok false.
• Do not upload text being transformed.
• If replacement backreferences are introduced, document and test the behavior separately.

Testing

Test repeated replacements, no matches, empty find strings, empty replacement strings, case-insensitive mode, whole-word mode, literal escaping, regex mode, invalid regex, and replacement-count accuracy.

PR checklist

• npm test passes for find-and-replace.
• Literal mode cannot accidentally run regex metacharacters.
• Invalid regex returns a structured error.
• Text remains browser-local.