AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools URL Parser Agent Guide

Agent guide for URL component extraction and query parameter parsing.

AGENTS.md

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

Project overview

This guide covers src/tools/url-parser/index.ts. The tool trims input, constructs a URL object, extracts protocol, host, hostname, port, path, query parameters, and fragment, and returns a structured UrlResult for both valid and invalid input.

Primary source files

  • src/tools/url-parser/index.ts defines meta, QueryParam, UrlResult, and parseUrl.
  • src/tools/url-parser/index.test.ts covers full parsing, invalid input, empty input, missing port, and missing query values.
  • src/tools/url-parser/Body.astro owns the browser inspector UI.
  • src/tools/url-parser/i18n.ts owns localized page copy.
  • src/lib/tools.ts registers tool metadata.

Setup commands

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

Change rules

  • Require an absolute URL accepted by the platform URL constructor unless a new relative-mode parser is added.
  • Return ok false and a clear Enter a URL message for blank input.
  • Preserve query parameter order as returned by searchParams iteration.
  • Return hash without the leading fragment marker.
  • Do not fetch, validate reachability, or resolve network addresses from the parsed URL.
  • Do not include real private URLs, ports, hosts, or query strings in public docs.
  • When adding repeated-query display behavior, test repeated keys explicitly.

Testing

Test full URLs, empty input, invalid input, explicit and missing ports, empty query arrays, repeated query keys, encoded query values, fragments, and protocol-specific edge cases.

PR checklist

  • npm test passes for url-parser.
  • Parser does not perform network activity.
  • Blank and invalid input return structured errors.
  • Public docs avoid real URLs and private hosts.