feat(cli): add introspect command for index facets and searchable attributes

[sarahdayan]

Summary

Adds the instantsearch introspect subcommand. Given an index name and credentials, it prints the index's facets and searchable attributes. The intent is to let an agent (or a developer) plan what to scaffold before calling add. Builds on #7052.

Examples

Credentials passed explicitly:

instantsearch introspect --index products --app-id XYZ --search-api-key abc --json

Credentials read from the manifest written by init:

instantsearch introspect --index products --json

How it works

Calls searchSingleIndex from algoliasearch with facets: ['*'] and attributesToHighlight: ['*']. Then:

• Facets are the top-level facets keys of the response
• Searchable attributes are the union of _highlightResult keys across the returned hits

When both --app-id/--search-api-key flags and a manifest are present, the flags win.

Failure codes

• missing_required_flag — --index missing, or no credentials available (no manifest + no flags)
• index_not_found — Algolia returned 404 for the index name
• credentials_invalid — Algolia returned 401/403 (app ID or search API key rejected)
• algolia_error — any other Algolia/transport failure
• invalid_manifest — the manifest exists but is malformed

Envelope change

The success envelope grows an optional data field, used here to carry { facets, searchableAttributes } without overloading filesCreated / nextSteps. Other commands keep working as before.

Why no replicas

Listing replicas requires settings-read permission, which the search-only API key doesn't grant. Leaving them out for now.

Checklist

• --index <name> --app-id X --search-api-key Y --json returns facets and searchable attributes
• --index <name> --json (no credential flags) reads credentials from the manifest
• Flag credentials take precedence over the manifest when both are present
• No manifest and no flags → missing_required_flag
• Missing --index → missing_required_flag
• Invalid index name → index_not_found
• Algolia returns 401/403 → credentials_invalid
• Network or other API errors → algolia_error
• Malformed manifest → invalid_manifest

Deferred from the amendment

After review, three amendment items were intentionally not implemented:

• algolia_error → network_error rename: not done. The original name is more honest as a catch-all — network_error reads as transport failure, but the catch also covers 5xx and other API errors. Renaming would lose information. A future split (network_error vs api_error) is cleaner than a flat rename.
• index_empty refusal: not done. An empty index is a state, not an error — the success envelope already represents it via empty searchableAttributes array. Forcing a refusal blocks consumers from acting on the (legitimately sparse) data.
• index_has_no_facets refusal: same shape as above. The empty facets: [] is the honest representation; consumers can decide whether to surface it as guidance.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 33 complexity

Metric	Results
Complexity	33

View in Codacy

_{TIP This summary will be updated as you push new changes.}

[pkg-pr-new]

More templates

• example-instantsearch-getting-started
• example-react-instantsearch-getting-started
• example-react-instantsearch-next-app-dir-example
• example-react-instantsearch-next-routing-example
• example-vue-instantsearch-getting-started

algoliasearch-helper

npm i https://pkg.pr.new/algolia/instantsearch/algoliasearch-helper@7053

instantsearch-ui-components

npm i https://pkg.pr.new/algolia/instantsearch/instantsearch-ui-components@7053

instantsearch.css

npm i https://pkg.pr.new/algolia/instantsearch/instantsearch.css@7053

instantsearch.js

npm i https://pkg.pr.new/algolia/instantsearch/instantsearch.js@7053

react-instantsearch

npm i https://pkg.pr.new/algolia/instantsearch/react-instantsearch@7053

react-instantsearch-core

npm i https://pkg.pr.new/algolia/instantsearch/react-instantsearch-core@7053

react-instantsearch-nextjs

npm i https://pkg.pr.new/algolia/instantsearch/react-instantsearch-nextjs@7053

react-instantsearch-router-nextjs

npm i https://pkg.pr.new/algolia/instantsearch/react-instantsearch-router-nextjs@7053

vue-instantsearch

npm i https://pkg.pr.new/algolia/instantsearch/vue-instantsearch@7053

commit: 708510b

[Copilot]

Pull request overview

Adds a new instantsearch introspect CLI subcommand that queries an Algolia index and reports discovered facet names and “searchable attributes” (inferred from _highlightResult keys). This extends the CLI beyond scaffolding by enabling automated planning before future add scaffolding steps.

Changes:

• Introduces the introspect command wired into the CLI program and command registry.
• Implements runIntrospect with manifest/flag credential resolution, Algolia querying, error classification, and human/JSON outputs.
• Extends the success envelope with an optional data payload and adds Jest coverage (including HTTP mocking via nock).

Reviewed changes

Copilot reviewed 9 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
yarn.lock	Adds lock entries for new test dependency (nock) and its transitive deps.
tsconfig.v4.json	Excludes packages/instantsearch-cli from TS v4 config scope.
packages/instantsearch-cli/src/program.ts	Registers the new introspect subcommand and adds it to known commands.
packages/instantsearch-cli/src/introspect.ts	Implements introspection logic, credential resolution, Algolia query, and output formatting.
packages/instantsearch-cli/src/envelope.ts	Adds optional data field to success envelopes for structured outputs.
packages/instantsearch-cli/package.json	Adds algoliasearch runtime dependency, nock dev dependency, and a build script.
packages/instantsearch-cli/tests/json-envelope.test.ts	Narrows generic JSON-envelope test to add only.
packages/instantsearch-cli/tests/introspect.test.ts	Adds comprehensive tests for introspect outputs, errors, and credential precedence.
packages/instantsearch-cli/tests/human-output.test.ts	Narrows generic human-output test to add only.
packages/instantsearch-cli/tests/utils/helpers.ts	Adds helpers for capturing IO and parsing JSON envelopes.
jest.config.js	Conditionally includes instantsearch-cli tests when algoliasearch major is v5.

---

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