feat: searchControls walkthrough in init and fix spurious diff noise

[chuckmeyer]

Summary

• algolia-agent init: adds an optional searchControls walkthrough after the replica prompts, covering all five supported fields (hitsPerPage, page, attributesToRetrieve, facets, responseFields) — each skippable by leaving blank
• _diff(): fixes spurious changes on every dry-run caused by the API expanding searchControls with default fields (query, page, responseFields, etc.) that were never in the original config — now only compares keys present in the new payload
• README: expands the searchControls field table to list all five fields and updates the init example to show the new prompts

Test plan

• pytest tests/test_cli.py -k init — 13 tests including test_init_with_search_controls and test_init_skip_search_controls
• pytest tests/test_cli.py -k diff — 5 tests including test_diff_no_false_positive_when_api_expands_search_controls and test_diff_detects_change_despite_api_expansion
• pytest tests/test_cli.py — full suite (49 tests)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR enhances the CLI’s init workflow by adding an optional interactive walkthrough for configuring searchControls, and adjusts _diff() to reduce dry-run noise caused by the API returning expanded/default searchControls fields. It also updates documentation and tests to reflect the new prompts and diff behavior.

Changes:

• Add an optional searchControls prompt flow to algolia-agent init (supports hitsPerPage, page, attributesToRetrieve, facets, responseFields).
• Update _diff() to compare only searchControls keys present in the new payload to avoid false-positive diffs from API-expanded defaults.
• Update README examples and extend tests to cover the new init prompts and diff behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/algolia_agent/cli.py	Adds searchControls init walkthrough and changes _diff() searchControls comparison to ignore API-added default keys.
tests/test_cli.py	Updates init-input fixtures and adds tests for the searchControls init flow and expanded-API diff behavior.
README.md	Documents the new init prompts and expands the searchControls field table.

Comments suppressed due to low confidence (1)

src/algolia_agent/cli.py:327

• _diff() filters the current agent's searchControls down to new_sc_keys. When the new payload has an explicitly empty searchControls object (or omits it entirely), new_sc_keys becomes empty and curr_sc_map is forced to {} for every index. That makes _diff() unable to report a real change where an existing non-empty searchControls would be cleared/removed. Consider tracking presence separately (missing vs {} vs None) and/or comparing per-index key sets instead of a global union so empty payloads can still surface a change when appropriate.

    # Only compare keys present in the new payload — the API expands searchControls
    # with default fields (query, page, responseFields, etc.) that we never sent,
    # which would otherwise cause a spurious diff on every dry-run.
    new_sc_keys = {
        k
        for t in new_payload.get("tools", [])
        for i in t.get("indices", [])
        for k in (i.get("searchControls") or {})
    }
    curr_sc_map = {
        i["index"]: {k: v for k, v in (i.get("searchControls") or {}).items() if k in new_sc_keys}
        for t in current.get("tools", [])
        for i in t.get("indices", [])
    }
    new_sc_map = {
        i["index"]: (i.get("searchControls") or {})
        for t in new_payload.get("tools", [])
        for i in t.get("indices", [])
    }
    if curr_sc_map != new_sc_map:
        curr_repr = json.dumps(next(iter(curr_sc_map.values()), None))
        new_repr = json.dumps(next(iter(new_sc_map.values()), None))
        lines.append(f"  searchControls: {curr_repr} → {new_repr}")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.