AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools JSON to YAML Agent Guide

Agent guide for JSON parsing, YAML dumping, and structured conversion errors.

AGENTS.md

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

Project overview

This guide covers src/tools/json-to-yaml/index.ts. The tool trims input, treats empty input as a valid blank result, parses JSON with JSON.parse, dumps parsed values through js-yaml, and returns structured ConvertResult errors for invalid JSON.

Primary source files

  • src/tools/json-to-yaml/index.ts defines meta, ConvertResult, and toYaml.
  • src/tools/json-to-yaml/index.test.ts covers simple objects, arrays, invalid JSON, and empty input.
  • src/tools/json-to-yaml/Body.astro owns the browser editor and output.
  • src/tools/json-to-yaml/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 JSON.parse as the validation boundary.
  • Return ok true with empty output for blank input.
  • Return ok false with an Invalid JSON prefix for parse failures.
  • Do not eval JSON-like input or accept comments unless a JSONC mode is explicitly added.
  • Do not send pasted JSON to a server.
  • When changing YAML dump options, update snapshots or string assertions to match.
  • Preserve ConvertResult shape for Body.astro.

Testing

Test objects, arrays, nested values, booleans, null, strings needing quoting, invalid JSON, empty input, whitespace-only input, and large pasted values if performance controls are added.

PR checklist

  • npm test passes for json-to-yaml.
  • Invalid JSON returns a structured error.
  • Blank input does not show an error.
  • Conversion remains browser-local.