AGENTS.md

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

Project overview

This guide covers src/tools/url-encoder/index.ts. The tool supports component mode through encodeURIComponent, full mode through encodeURI, and decode mode through decodeURIComponent with structured error handling for malformed percent-encoded input.

Primary source files

• src/tools/url-encoder/index.ts defines meta, EncodeMode, DecodeResult, encodeUrl, and decodeUrl.
• src/tools/url-encoder/index.test.ts covers component mode, full mode, defaults, Unicode round trips, malformed decode input, empty input, and simple decoding.
• src/tools/url-encoder/Body.astro owns the browser mode controls.
• src/tools/url-encoder/i18n.ts owns localized copy.
• src/lib/tools.ts auto-discovers metadata.

Setup commands

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

Change rules

• Keep component mode as the default because it is safest for query parameter values.
• Use encodeURI only for full-mode input where URL separators should remain readable.
• Return ok true with empty output for empty decode input.
• Catch URIError from malformed percent sequences and return ok false.
• Do not normalize or fetch URLs in this tool; it only encodes and decodes strings.
• Do not publish real URLs or private query strings in public docs.
• If form-style plus-space decoding is added, expose it as an explicit mode with tests.

Testing

Test component encoding, full URI encoding, default mode, reserved characters, Unicode round trip, malformed percent sequences, empty decode input, and future plus-space mode if introduced.

PR checklist

• npm test passes for url-encoder.
• Malformed decode input never throws into the UI.
• Full mode and component mode remain visibly distinct.
• No real query strings are used in public generated docs.