AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools SQL Formatter Agent Guide

Agent guide for SQL formatting, dialect selection, and error handling in alexandrai-tools.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools SQL Formatter in the alexandrai-tools project.

Project overview

This guide covers src/tools/sql-formatter/index.ts. The tool trims SQL input, calls the sql-formatter package with a selected dialect, returns formatted output for valid input, and converts formatter exceptions into structured FormatResult errors.

Primary source files

  • src/tools/sql-formatter/index.ts defines meta, FormatResult, SqlDialect, and formatSql.
  • src/tools/sql-formatter/index.test.ts covers basic formatting, MySQL dialect, empty input, and multiline queries.
  • src/tools/sql-formatter/Body.astro owns input, dialect selection, and output display.
  • src/tools/sql-formatter/i18n.ts owns localized page copy.
  • src/lib/tools.ts auto-discovers metadata for route and hub rendering.

Setup commands

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

Change rules

  • Keep empty input as ok true with empty output so users can clear the editor without seeing an error.
  • Keep SqlDialect aligned with languages supported by the sql-formatter dependency.
  • Catch formatter exceptions and return FormatResult with ok false and an error message.
  • Do not execute SQL or connect to databases; this tool only formats text.
  • Do not send SQL text to a server or logging pipeline.
  • When adding dialects, add type values, UI options, tests, and copy together.
  • Keep the formatter wrapper pure so tests can call it without browser state.

Testing

Test default SQL formatting, each supported dialect, empty input, multiline input, syntax or dialect errors, whitespace trimming, large query behavior, and UI copy that makes clear the tool does not execute queries.

PR checklist

  • npm test passes for sql-formatter.
  • No SQL execution or network call is introduced.
  • Dialect options match the typed union.
  • Formatter errors return ok false rather than throwing into the UI.