prism: Instructions file for Codex

AGENTS.md — prism

🔻 The agent's data reader. Any JSON/JSONL blob becomes its shape and the slice you asked for, not the whole thing. What scout does for the web and lens does for code, prism does for structured data. CLI + web + MCP. Part of tools-for-agents.

Setup

node --version                                   # 22+ required. Nothing to install.
npm test                                         # = node --test
echo '{"a":{"b":[1,2,3]}}' | node src/cli.js shape -
node src/cli.js read data.json --path 'items[*].id'
node src/cli.js find config.json "timeout"
node src/cli.js serve                             # the web view → http://localhost:7970
npm run mcp                                       # the MCP server, stdio

Zero runtime dependencies, and that is a hard rule. No dependencies in package.json, ever. Node 22+ gives you fetch, a test runner, and everything else this needs. If a feature seems to need a library, the feature is too big — ship the smaller version.

The four verbs

• shape <src> — the skeleton: keys→types, array lengths, nesting.
• read <src> --path P — the subtree at path P, token-budgeted.
• find <src> "<query>" — the paths where a key/value lives (the input to read).
• diff <a> <b> — the paths that changed between two blobs (added / removed / changed), by structure not by text; node- and hit-bounded, summary counts always complete.

<src> is a file, an http(s) URL, or - (stdin). Paths: data.items[0].name, users[*].id, logs[0:20] (a slice; [:20]/[100:] too, bounds clamp), logs[-1] (negative = from the end; [-20:] = last twenty), $. Formats: JSON/JSONL auto-detect; CSV/TSV from a .csv/.tsv source or --format csv → an array of row objects keyed by the header, with conservative coercion (a number only if it round-trips exactly).

The rules this repo is built on

1. It reads UNTRUSTED data, so every operation is BOUNDED. This is the whole identity of the tool. Input is byte-capped before JSON.parse (all-or-nothing; a 2 GB file is a frozen process). shape is depth- and key-bounded. read is token-budgeted. find is node-bounded. Any new feature that traverses or allocates must carry its own ceiling — grep the DoS lesson the kit already paid for (anvil's 40 GB diff).