Skip to content

feat: distinguish empty results from broken index in search output #3

Description

@ktappdev

Problem

contexting search-hints "query" --json returns [] in two very different situations:

  1. No matches — index exists and is healthy, query just didn't match anything
  2. Broken/missing index — index file doesn't exist or is corrupted, search silently returns nothing

LLM agents and tools can't tell the difference. They assume "empty results = nothing relevant" when it might mean "your index is broken."

Proposed Solution

Wrap JSON output in an envelope with metadata:

{
  "source": "memory | snapshot | none",
  "index_generated_at": "2026-06-16T10:00:00Z",
  "results": [
    {"path": "src/auth.go", "type": "file", "score": 85, "matches": ["..."]}
  ]
}

Where source:

  • "memory" — results from live watch server
  • "snapshot" — results from .ctx/ctx_index.json file
  • "none" — no index available, results always empty

Implementation Notes

  • Modify resultsToJSON or create new envelopeToJSON wrapper
  • Track source in the search flow (already have usedMemory bool in command_search.go:84)
  • index_generated_at from ContextIndex.GeneratedAt (already in index JSON)
  • For --dir-summary mode, add same envelope
  • Non-JSON output (--json=false) unchanged

Acceptance Criteria

  • --json output includes source field
  • source: "none" when index missing or corrupted
  • source: "memory" when connected to live watch server
  • source: "snapshot" when reading from index file
  • index_generated_at included when available
  • Backward compatible: results array has same shape as current output

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions