AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Fuel Cost in the alexandrai-tools project.

Project overview

This guide covers src/tools/fuel-cost. calcFuelCost accepts distance in kilometres, efficiency in mpg, L/100km, or km/L, and price per litre. It converts mpg through miles and US gallons, handles direct L/100km and km/L formulas, and returns litres needed plus total cost.

Primary source files

• src/tools/fuel-cost/index.ts defines meta, EfficiencyUnit, FuelCostResult, and calcFuelCost.
• src/tools/fuel-cost/index.test.ts covers L/100km, km/L, mpg, invalid distance, invalid efficiency, and zero fuel price.
• src/tools/fuel-cost/Body.astro owns distance, efficiency, unit, price, and result presentation.
• src/tools/fuel-cost/i18n.ts owns localized labels.
• src/lib/tools.ts registers the tool metadata.

Setup commands

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

Change rules

• Return zero litres and zero cost when distance or efficiency is not positive.
• Return zeros when price per litre is negative.
• Allow zero price per litre.
• For mpg, convert kilometres to miles and gallons to litres.
• For L/100km, multiply distance divided by one hundred by efficiency.
• For km/L, divide distance by efficiency.
• Keep currency selection outside the pure calculation.

Testing

Test all efficiency units, zero price, negative price, zero distance, zero efficiency, decimal inputs, displayed rounding, currency labels, and UI validation.

PR checklist

• npm test passes for fuel-cost.
• Calculator formulas, units, and rounding expectations are documented.
• Currency and display formatting remain outside pure helpers.
• Invalid-input behavior is covered by tests and UI validation.