jqlisted

# jq — JSON processing with the jq CLI ## When to use - User wants to extract, filter, transform, aggregate, or pretty-print JSON with `jq` - Input is JSON / JSON array / NDJSON (newline-delimited JSON), API payloads, logs, configs - Prefer this over writing a throwaway Python/Node script for the same JSON job Do **not** use when: - File is binary, CSV, XML, YAML-only (unless already converted to JSON) - Task is general bash/Python scripting with no JSON core - User only needs to open/edit JSON in an editor (no filter) ## Prerequisites ```bash command -v jq >/dev/null || { echo "jq not installed"; exit 1; } jq --version # expect 1.6+ ``` If missing: tell the user to install (`brew install jq` / `apt install jq`) and STOP. ## Procedure Work phases in order. Do not skip. Prefer pure `jq` over `python`/`node` for JSON work. ### Phase 1 — Structure analysis 1. Identify inputs: path(s), stdin, or API response the user provided. 2. Peek schema before complex filters: - Small file: `jq 'type, (if type=="array" then length else keys end)' <file>` - Huge / unknown: `jq -c 'limit(1; .)' <file>` or first NDJSON line via `head -n 1` - Validate: `jq empty <file>` — non-zero exit → report parse error and STOP 3. Note shape: object vs array vs NDJSON stream; nested keys needed; size class (<10MB / large). 4. **Completion:** input path(s) known, type known, filter target keys identified (or error reported). ### Phase 2 — Filter construction Design filter with explicit