AlexandrAI AGENTS.md
agents-md

FileGraph API Routes Test Contract Agent Guide

Agent guide for FileGraph route handlers, singleton service wiring, serializers, and deterministic tests.

AGENTS.md

Guidance for coding agents working on FileGraph API Routes Test Contract in the FileGraph project.

Project overview

This guide covers the FileGraph API route surface, src/lib/filegraph/service-instance.ts, and route-focused tests. Routes are intentionally thin: they validate input when needed, obtain the singleton service, delegate to FileGraphService, serialize notes when returning note records, and map validation or unknown-note failures to JSON error responses.

Primary source files

  • src/app/api/notes/route.ts lists notes and creates manual notes.
  • src/app/api/notes/[id]/route.ts reads and updates a specific note.
  • src/app/api/notes/[id]/reanalyze/route.ts queues analysis for one note.
  • src/app/api/graph/route.ts returns the current graph snapshot.
  • src/app/api/retrieval/context/route.ts returns retrieval context from query and noteId params.
  • src/app/api/vault/rescan/route.ts forces a vault rescan.
  • src/lib/filegraph/service-instance.ts owns the singleton and the testing override.
  • src/lib/filegraph/api.ts defines NoteResponse and serializeNote.
  • src/app/api/notes/route.test.ts and src/app/api/ingest/notes/route.test.ts show the route test pattern.

Setup commands

pnpm install pnpm test pnpm lint pnpm build pnpm dev

Change rules

  • Keep route handlers thin. Business rules belong in FileGraphService, not duplicated across routes.
  • Use zod at route boundaries for request bodies that create or mutate notes.
  • Use serializeNote whenever returning full note records to the UI.
  • Preserve setFileGraphServiceForTesting so route tests can run with temp roots and fake analyzers.
  • Disable watchers in tests to avoid filesystem timing noise.
  • Return JSON error payloads for invalid requests and unknown notes; keep statuses consistent with current route behavior.
  • Do not add route-level network calls. Ingest callers and analyzer implementations are separate responsibilities.
  • When adding a route, add a route test that wires a temporary service and cleans it up after the test.

Testing

Add tests for GET notes, POST manual note validation, GET note unknown id, PUT manual update, POST reanalyze, GET graph, GET retrieval context, POST rescan, and route cleanup. Route tests should use temporary roots, fake analyzers, waitForIdle when needed, and destroy the service afterward.

PR checklist

  • Every route delegates to FileGraphService for state changes.
  • Route tests do not depend on a real analyzer or persistent vault.
  • Serializers expose only the fields the UI expects.
  • No test fixture or public guide includes local hosts, real URLs, or absolute user paths.