AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools JSONPath Tester Agent Guide

Agent guide for the supported JSONPath subset: dot keys, array indices, wildcards, negative indices, and recursive descent.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools JSONPath Tester in the alexandrai-tools project.

Project overview

This guide covers src/tools/jsonpath-tester. query parses JSON, requires paths to start with $, tokenizes a small JSONPath subset, supports plain keys, array indices, negative array indices, wildcards over arrays and objects, recursive descent by key, and returns arrays of matched values.

Primary source files

  • src/tools/jsonpath-tester/index.ts defines meta, QueryResult, tokenize, applyToken, recurse, and query.
  • src/tools/jsonpath-tester/index.test.ts covers root selection, nested array object access, array wildcard, recursive descent, invalid JSON, missing dollar prefix, and missing keys.
  • src/tools/jsonpath-tester/Body.astro owns JSON input, path input, sample data, and result rendering.
  • src/tools/jsonpath-tester/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

  • Reject empty JSON input.
  • Reject invalid JSON with the parser message included.
  • Reject paths that do not start with dollar sign.
  • Return the root value when path is exactly dollar sign.
  • Support bracket wildcard on arrays and objects.
  • Support non-negative and negative numeric array indices.
  • Return an empty result array for missing keys rather than an error.

Testing

Test every supported path token, root selection, missing paths, invalid JSON, invalid path prefix, negative indices, object wildcards, array wildcards, recursive descent, and unsupported JSONPath syntax behavior.

PR checklist

  • npm test passes for jsonpath-tester.
  • Pure helper behavior and browser UI behavior are aligned.
  • Generated CSS, Markdown, JSON, or image output remains browser-local.
  • Invalid input, copy behavior, and privacy expectations are covered.