AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools UTM Builder Agent Guide

Agent guide for appending UTM campaign parameters to absolute or relative URLs.

AGENTS.md

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

Project overview

This guide covers src/tools/utm-builder/index.ts. The tool parses absolute URLs with URL, falls back to a placeholder origin for relative input, sets source, medium, campaign, term, and content parameters when present, preserves existing query strings, and reconstructs relative URLs manually after fallback parsing.

Primary source files

  • src/tools/utm-builder/index.ts defines meta, UtmParams, and buildUtmUrl.
  • src/tools/utm-builder/index.test.ts covers basic UTM output, expected absolute output, encoded spaces, preserving existing query parameters, optional term and content, and omitted optional parameters.
  • src/tools/utm-builder/Body.astro owns browser controls.
  • src/tools/utm-builder/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 URL parsing for absolute inputs.
  • Use a placeholder origin only as a relative-input fallback.
  • Set source, medium, and campaign only when values are present.
  • Set term and content only when provided.
  • Preserve existing query parameters.
  • For relative input, append with ampersand when base already has a query string.
  • Avoid hardcoding analytics policy or campaign naming rules in pure URL building.

Testing

Test absolute URLs, relative URLs, existing query strings, spaces and special characters, missing optional parameters, all optional parameters, empty source or medium values, fragments if supported, and UI copy output.

PR checklist

  • npm test passes for utm-builder.
  • Generated output shape, escaping, and invalid-input behavior remain documented.
  • Browser-local generation stays free of hidden network calls.
  • UI labels, metadata, and tests update together for behavior changes.