AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Add to Calendar Agent Guide

Agent guide for the Add to Calendar link and ICS generator in alexandrai-tools.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Add to Calendar in the alexandrai-tools project.

Project overview

This guide covers src/tools/add-to-calendar/index.ts. The tool defines CalendarEvent, builds a provider calendar render link from event fields, and generates an ICS string with escaped text fields and CRLF line endings. Keep the core functions pure so the Body.astro layer can focus on form state and downloads.

Primary source files

  • src/tools/add-to-calendar/index.ts defines meta, CalendarEvent, buildGoogleCalUrl, buildIcs, and private ICS escaping.
  • src/tools/add-to-calendar/index.test.ts covers query encoding, optional fields, ICS envelope lines, CRLF termination, and escaping.
  • src/tools/add-to-calendar/Body.astro owns the browser form and download interaction.
  • src/tools/add-to-calendar/i18n.ts owns localized page copy.
  • src/lib/tools.ts auto-discovers the tool metadata for the hub and route.

Setup commands

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

Change rules

  • Keep CalendarEvent date strings in the existing compact calendar format; do not add timezone parsing without tests for all call sites.
  • Escape backslashes, semicolons, commas, and newlines before writing SUMMARY, DESCRIPTION, or LOCATION lines.
  • Keep ICS output CRLF-delimited and final-line terminated.
  • Do not require details or location; both are optional and should be omitted when absent.
  • Keep URL construction inside URLSearchParams so query values remain encoded.
  • Do not embed real event URLs or private locations in fixtures, docs, or examples.
  • If UID, DTSTAMP, or organizer fields are added, test deterministic output or inject stable clock data.

Testing

Test basic link generation, encoded title/details/location, date range preservation, ICS envelope structure, optional field omission, text escaping, CRLF line endings, and empty or whitespace-only event fields if UI validation changes.

PR checklist

  • npm test passes for add-to-calendar.
  • ICS output remains valid for plain text and punctuation-heavy event names.
  • Body.astro still downloads the exact string returned by buildIcs.
  • No public guide includes real calendar links or private event details.