AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools User Agent Parser Agent Guide

Agent guide for local browser, OS, and device detection from user agent strings.

AGENTS.md

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

Project overview

This guide covers src/tools/user-agent-parser/index.ts. The tool uses ordered regular expressions to classify device type, operating system, OS version, browser, and browser version from a supplied user agent string. Detection order matters because several browsers include compatibility tokens from other browsers.

Primary source files

  • src/tools/user-agent-parser/index.ts defines meta, UAResult, NT_MAP, and parseUA.
  • src/tools/user-agent-parser/index.test.ts covers Chrome on Windows, Safari on iPhone, Firefox, Edge, and bot detection.
  • src/tools/user-agent-parser/Body.astro owns the browser input and result display.
  • src/tools/user-agent-parser/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 device detection before OS and browser labels so bots and mobile devices are identified early.
  • Keep browser detection ordered from most specific to least specific.
  • Map Windows NT values through NT_MAP and fall back to the raw value when unknown.
  • Do not promise exhaustive fingerprinting accuracy; user agent parsing is heuristic.
  • Do not transmit or log pasted user agent strings.
  • When adding a browser or OS, add a representative test string.
  • Avoid publishing full real user agent strings in generated public guides.

Testing

Test bot, mobile, tablet, desktop, iOS, iPadOS, Android, Windows, macOS, Linux, Chrome, Edge, Opera, Samsung Browser, Safari, Firefox, and legacy browser patterns. Include ordering tests for browsers that contain Chrome-compatible tokens.

PR checklist

  • npm test passes for user-agent-parser.
  • Specific browser rules remain before Chrome fallback.
  • Unknown values degrade gracefully.
  • No real user agent logs are added.