If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/simeji/jid shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 4w ago
• 10 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 89% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live simeji/jid repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/simeji/jid.

What it runs against: a local clone of simeji/jid — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in simeji/jid | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 55 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of simeji/jid. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/simeji/jid.git
#   cd jid
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of simeji/jid and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "simeji/jid(\\.git)?\\b" \\
  && ok "origin remote is simeji/jid" \\
  || miss "origin remote is not simeji/jid (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/jid/jid.go" \\
  && ok "cmd/jid/jid.go" \\
  || miss "missing critical file: cmd/jid/jid.go"
test -f "engine.go" \\
  && ok "engine.go" \\
  || miss "missing critical file: engine.go"
test -f "json_manager.go" \\
  && ok "json_manager.go" \\
  || miss "missing critical file: json_manager.go"
test -f "query.go" \\
  && ok "query.go" \\
  || miss "missing critical file: query.go"
test -f "terminal.go" \\
  && ok "terminal.go" \\
  || miss "missing critical file: terminal.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 55 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~25d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/simeji/jid"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

jid is an interactive terminal UI for exploring JSON data incrementally using dot-path queries and JMESPath expressions. It provides real-time filtering, tab-completion, suggestion candidates, and synchronized JSON view highlighting as you navigate nested structures—similar to jq but with an interactive incremental drill-down interface rather than command-line piping. Single-package CLI tool: cmd/jid/jid.go is the entry point; core engine lives in engine.go (query execution), json_manager.go (JSON parsing/filtering), terminal.go (TUI interaction using termbox), query.go (query parsing), suggestion.go (autocomplete), and config.go (user settings). Modular design with each subsystem in its own file with paired _test.go.

DevOps engineers, API developers, and data analysts who need to explore complex JSON responses from APIs, logs, or config files without writing jq commands; users who prefer interactive discovery over memorizing query syntax.

Active and production-ready. The project uses GitHub Actions for CI/CD (test.yml, release.yml), has comprehensive unit tests (every major module has _test.go files), and is packaged across multiple package managers (Homebrew, MacPorts, pkg, scoop, repology). It appears actively maintained with structured release automation (.goreleaser.yml) and is written in Go 1.20+.

Low risk. Single maintainer (simeji) with stable dependency set (9 direct deps, all well-known: termbox-go for UI, jmespath for query engine, json-iterator for parsing). No obvious breaking-change history. Key dependency risk: termbox-go is a 2014 library with limited maintenance, but it's stable and a thin wrapper around platform termbox libraries. Otherwise minimal external risk.

No visible recent changes in the provided data, but the presence of modern Go modules (go.mod with 1.20+), active GitHub Actions workflows, and .goreleaser.yml suggest ongoing maintenance and binary releases. No open issue/PR data provided to assess current active work.

git clone https://github.com/simeji/jid.git
cd jid
go install ./cmd/jid
echo '{"test":"data"}' | jid

Daily commands: No build step needed. Run directly: echo '{"aa":"bb"}' | jid or build from source: go build -o jid ./cmd/jid/ then use the binary. Releases available at https://github.com/simeji/jid/releases.

• cmd/jid/jid.go — Entry point for the CLI application; understand how the TUI is initialized and the main event loop works.
• engine.go — Core orchestrator that ties together query execution, JSON management, and UI rendering; essential for understanding the dig-down flow.
• json_manager.go — Manages JSON parsing, filtering, and state; handles the data transformations that power incremental navigation.
• query.go — Parses and executes JMESPath and dot-notation queries; critical for understanding how filters are applied.
• terminal.go — UI rendering layer using termbox-go; handles key bindings, suggestion display, and JSON visualization on screen.
• suggestion.go — Generates autocomplete suggestions and JMESPath function hints; powers the interactive discovery experience.
• config.go — Configuration and keymapping loading from TOML; sets up user preferences and input handling.

• engine.go (Engine) (Go concurrency patterns, custom event loop) — Central state machine; handles mode transitions, input events, query execution, and triggers UI updates.
  • Failure mode: Panics on malformed query or memory exhaustion; causes ungraceful TUI exit without cleanup.
• json_manager.go (JSONManager) (go-simplejson, go-jmespath, json-iterator/go) — Owns current JSON document and applies filters; parses input, projects fields, validates structure.
  • Failure mode: Returns error on invalid JSON or failed filter application; state remains unchanged until next valid query.
• query.go (Query Parser) (Regex/string parsing, go-jmespath validation) — Tokenizes and validates user input; distinguishes JMESPath expressions from simple dot-notation.
  • Failure mode: Returns parse error; prevents invalid queries from reaching json_manager.go.
• terminal.go (TUI Renderer) (termbox-go, jsoncolor, go-runewidth for Unicode support) — Draws all visual elements: JSON pane, query input, suggestions, status bar; captures keyboard input.
  • Failure mode: Terminal corruption if resize signal interrupts mid-draw; recovered on next render cycle.
• suggestion.go (Autocomplete Engine) (Recursive key extraction, JMESPath function introspection) — Inspects current JSON and query context to generate field and function candidates.
  • Failure mode: Returns empty suggestions if JSON is malformed; fallback to no autocomplete.
• config.go (Configuration) (BurntSushi/toml, file I/O) — Loads user keymaps and preferences from TOML; provides defaults if config missing.
  • Failure mode: Silently falls back to hardcoded defaults on parse error; no error message to user.

• User stdin → json_manager.go — Initial JSON document piped or redirected into jid; parsed and stored in memory.
• terminal.go (key events) → engine.go — User keypresses captured by TUI; routed to engine's event handler for state transitions.
• engine.go → query.go — User input string forwarded for parsing into a Query object.
• query.go → json_manager.go — Parsed Query applied as a filter; returns projected JSON subset.
• suggestion.go → terminal.go — Autocomplete candidates rendered as overlay during interactive input.
• json_manager.go → terminal.go — Current (filtered) JSON document sent to renderer for syntax-highlighted display.
• undefined → undefined — undefined

Add a new keybinding

1. Define the key action constant in keymap.go (keymap.go)
2. Add the key-to-action mapping in config.go's default keymap initialization (config.go)
3. Handle the action in engine.go's main event loop (the function that processes user input) (engine.go)

Add support for a new query syntax or filter

1. Implement the parsing logic in query.go's Filter or Expression parsing functions (query.go)
2. Extend json_manager.go's Apply or Filter method to execute the new syntax (json_manager.go)
3. Add suggestion templates for the new syntax in suggestion.go (suggestion.go)

Extend autocomplete suggestions

1. Add candidate generation logic in suggestion.go (Functions like GetSuggestions, GetFieldSuggestions) (suggestion.go)
2. Wire the suggestions into terminal.go's rendering code to display them on screen (terminal.go)

• Go 1.20 — Fast, single binary deployment; ideal for a CLI tool distributed via Homebrew and cross-platform builds.
• termbox-go — Lightweight, cross-platform terminal UI library for real-time key capture and screen rendering without external dependencies.
• go-jmespath — Battle-tested JMESPath implementation; allows powerful, expression-based JSON queries beyond simple dot-notation.
• TOML configuration — Human-readable user config format for custom keymaps and preferences; BurntSushi/toml is stable and well-integrated.
• jsoncolor — Syntax highlighting for JSON output in terminal; improves readability of nested structures during interactive exploration.

• Single-binary compiled executable vs. interpreted/scripted tool

  • Why: Go compiles to a native binary with no runtime dependencies, making distribution and installation trivial.
  • Consequence: Slightly longer build time and larger binary size (~20–30 MB), but users have zero setup friction.

• termbox-go for UI instead of full TUI framework (e.g., bubbletea)

  • Why: Minimal, low-level control over terminal rendering; keeps the binary small and dependencies lean.
  • Consequence: Manual screen layout and event loop management required; more code in terminal.go, but simpler overall architecture.

• In-memory JSON filtering (no streaming/pagination)

  • Why: Simplifies query execution and state management; fast enough for typical JSON documents.
  • Consequence: Large JSON files (>100 MB) may cause memory pressure or latency; not suitable for streaming data sources.

• Real-time data streaming or live JSON feeds
• Remote JSON data sources or HTTP fetching
• Multi-file or multi-document batch processing
• Persistent data export (read-only exploration tool)
• Authentication or security-restricted JSON handling

Termbox-go is platform-specific and may require system termbox libraries (libtermbox on Linux). Interactive mode requires a TTY and will fail silently if piped in a non-interactive context—design assumes direct terminal control. Query history is stored in memory (history.go) and not persisted across sessions by default. Config file parsed from ~/.jidrc (TOML format)—missing file is silently ignored, so misconfiguration is easy to miss.

• JMESPath — jid's query language relies on the jmespath/go-jmespath library; understanding JMESPath syntax (pipes, wildcards, filters, functions) is essential to extend suggestion.go and query.go
• Termbox (TUI library) — terminal.go uses nsf/termbox-go to render UI, handle raw keyboard input, and manage screen buffers; essential to modify keybindings or layout
• Incremental/Progressive Filtering — jid's core UX: render results after each keystroke (engine.go's event loop) to show immediate feedback; differs from batch-mode tools like jq
• REPL (Read-Eval-Print Loop) — jid implements a REPL pattern (terminal.go + engine.go): read user input, evaluate query against JSON, print filtered result, loop for next input
• Trie-based Autocomplete — suggestion.go likely uses a trie or similar structure to efficiently generate field candidates and function names; understanding this is needed to optimize or extend suggestions
• State Machine (TUI Design) — engine.go models the interactive session as a state machine (input mode, query evaluation, result rendering); modifying behavior requires understanding state transitions
• Go Interfaces & Composition — jid uses Go interfaces (implicitly satisfied by json-iterator, simplejson) to decouple JSON parsing; adding alternative JSON backends or query engines requires understanding this pattern

• stedolan/jq — Original inspiration and reference implementation; jid provides the interactive UI wrapper around similar query semantics
• jqlang/jq — Active community fork of jq with modern maintenance; both repos target JSON querying with similar syntax
• mikefarah/yq — YAML equivalent tool with similar interactive query paradigm; users of jid often use yq for YAML exploration
• nix-community/nix-output-monitor — Go CLI TUI tool using termbox-go; shares same low-level rendering library and interaction patterns
• junegunn/fzf — Interactive filtering CLI; inspired the suggestion/autocomplete UX pattern that jid uses for query discovery

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for terminal UI interactions in terminal_test.go

The terminal.go file handles critical UI interactions (key bindings, rendering, navigation) but terminal_test.go likely has limited coverage of terminal multiplexing scenarios. The keymap.go exists separately but integration between keymap and terminal rendering isn't well-tested. This would catch regressions in the interactive experience.

• [ ] Review terminal_test.go and keymap_test.go to identify untested interaction paths
• [ ] Add tests for key event handling chains (e.g., tab completion flow, arrow navigation with suggestions)
• [ ] Add tests for rendering state after terminal resize events and mode changes
• [ ] Test interaction between query.go mutations and terminal state updates

Add missing tests for edge cases in json_manager.go and query.go

The JSON processing pipeline (json_manager.go handling JSON parsing/filtering, query.go managing query state) are core to correctness. Given the dependency on jmespath/go-jmespath for JMESPath support (mentioned in README), there are likely untested edge cases around malformed JSON, invalid JMESPath expressions, and empty result sets.

• [ ] Review json_manager_test.go for coverage of: null values, deeply nested structures, large JSON files, circular references
• [ ] Review query_test.go for coverage of: invalid JMESPath syntax, queries on empty objects/arrays, pipe chaining errors
• [ ] Add specific test cases for error messages returned to users (suggestion.go integration)
• [ ] Add regression tests based on any reported GitHub issues

Add GitHub Action workflow for cross-platform binary testing in test.yml

The .goreleaser.yml suggests multi-platform builds (Linux, macOS, Windows), but test.yml likely only runs on ubuntu-latest. The terminal.go and terminal_test.go depend on termbox-go which has platform-specific behavior. Testing on macOS and Windows in CI would catch platform-specific bugs before release.

• [ ] Review .github/workflows/test.yml to confirm it only runs on ubuntu-latest
• [ ] Extend test.yml to run test suite on macos-latest and windows-latest matrices
• [ ] Ensure config_test.go, history_test.go run on all platforms (config paths differ per OS)
• [ ] Verify release.yml correctly builds artifacts after test.yml passes on all platforms

• Add tests for config.go—it has a _test.go file but likely incomplete coverage for edge cases like malformed ~/.jidrc parsing or missing config directory.
• Improve suggestion.go autocomplete for nested JMESPath expressions—currently may not suggest array indexing syntax [*] or filter expressions like [?type=='user'].
• Add integration tests in cmd/jid/jid_test.go that pipe real JSON stdin and verify filtered output—tests exist but may miss end-to-end scenarios with complex queries.

The jid codebase has moderate security concerns primarily related to dependency management and outdated packages. The most critical issues are: (1) Go 1.20 is end-of-life with no active security support, (2) pkg/errors v0.8.0 is unmaintained since 2016, and (3) bitly/go-simplejson v0.5.0 lacks any recent maintenance. Additionally, input validation for JSON processing and JMESPath query execution could be strengthened. The application's interactive nature with user-supplied JSON and queries warrants careful input validation to prevent injection and DoS attacks. Immediate action recommended: upgrade Go version, remove or replace unmaintained dependencies, and implement comprehensive input validation.

• High · Outdated Go Version — go.mod. The project targets Go 1.20, which reached end-of-life on December 6, 2023. Using outdated Go versions exposes the codebase to known security vulnerabilities and lack of security updates. Fix: Update to Go 1.21 or later (preferably the latest stable version). Update go.mod to reflect the newer version requirement.
• High · Vulnerable Dependency: pkg/errors — go.mod. The package 'github.com/pkg/errors v0.8.0' is outdated (released 2016). This dependency is no longer maintained and may contain unpatched security vulnerabilities. Modern Go versions include error wrapping features natively. Fix: Replace pkg/errors with native Go error wrapping (Go 1.13+). Remove the dependency and refactor error handling to use 'fmt.Errorf("%w", err)' pattern.
• High · Vulnerable Dependency: go-simplejson — go.mod. The package 'github.com/bitly/go-simplejson v0.5.0' is significantly outdated. The last update was in 2013. No security updates or maintenance for over a decade indicates potential vulnerabilities. Fix: Review if this dependency is still necessary. Consider using 'encoding/json' from the standard library or switching to actively maintained alternatives like 'github.com/tidwall/gjson' or 'github.com/json-iterator/go'.
• Medium · Multiple Outdated Dependencies — go.mod. Several dependencies have not been updated recently: go-runewidth (0.0.9), termbox-go (1.1.1), jsoncolor (0.0.0-20170215171346), and mattn/go-colorable (0.0.9). These may lack recent security patches and bug fixes. Fix: Run 'go get -u' to update dependencies to their latest versions. Review and test each update for compatibility. Consider using 'go mod tidy' and running tests after updates.
• Medium · Potential Command Injection Risk — cmd/jid/jid.go, query.go. The application processes user input through interactive terminal queries (jid.go implements a JSON filtering tool). If queries are constructed without proper sanitization or validation, there could be injection risks when executing JMESPath expressions. Fix: Ensure all user inputs are validated before being passed to query engines. Use only safe parsing methods for JMESPath expressions. Avoid any string concatenation for building queries. Add input validation tests.
• Medium · Lack of Input Validation in JSON Processing — json_manager.go. The json_manager.go file processes JSON data from user input without explicit validation of size limits or structure complexity. Large or maliciously crafted JSON could cause DoS (denial of service) through memory exhaustion or parsing performance issues. Fix: Implement maximum file size limits before processing JSON. Add timeouts for JSON parsing operations. Consider limiting nesting depth. Add defensive validations for JSON structure complexity.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.