search-resolver

Imported from vtex-apps/search-resolver (AGENTS.md). Install upstream with npx skills add vtex-apps/search-resolver. Copyright stays with the author.

AGENTS.md — search-resolver

Repository Purpose

vtex.search-resolver is a VTEX IO backend service (builder node) that implements the GraphQL resolvers for the catalog, search, and orders schema published by vtex.search-graphql.

It is the resolver layer of the Intelligent Search stack. The GraphQL schema (the contract) lives in vtex.search-graphql; this app loads that schema at runtime via the dependency vtex.search-graphql/graphql and registers its resolvers + directives against it (see node/index.ts).

Where it sits in the IS topology

Sources of Truth

Architecture

The service is a pure GraphQL plugin: node/index.ts exports new Service({...}) with no custom HTTP routes. vtex.search-graphql (declared as a dependency) provides the schema at vtex.search-graphql/graphql. At runtime, the IO platform composes the schema + the resolvers exported here.

GraphQL request ─► vtex.graphql-server / @vtex/api Service runtime
                    └─► schema (imported from vtex.search-graphql)
                         └─► resolvers (composed in node/resolvers/index.ts)
                              ├─ Query.product / facets / autocomplete / topSearches / …
                              ├─ field resolvers on Product, SKU, Brand, Category, Offer, AssemblyOption, …
                              ├─ benefits field resolvers (promotions, discount lists)
                              └─ schemaDirectives (@cacheControl, @withSegment, …)
                                   └─► clients.{search, intelligentSearchApi, intsch, checkout, rewriter}

Resolver organization

Endpoint switching

PLP (productSearch / products / productSuggestions / facets) always uses intsch. There is no shouldUseNewPLPEndpoint toggle.

These are per-account app settings, not FeatureHub flags. Toggling them changes which client takes the hot path.

Caches and timeouts

Configured in node/index.ts:

metrics.trackCache(<name>, <cache>) exposes hit/miss to platform observability.

External APIs (outbound policies)

From manifest.json policies:

CI

.github/workflows/pull-request.yml runs three jobs on PR:

1. io-app-test — vtex/action-io-app-test runs builder-aware Jest in each builder directory.
2. lint — vtex/action-lint runs the linter (root yarn lint → cd node && yarn lint → tsc --noEmit).
3. Cypress — vtex/action-io-app-cypress@v1 runs the vtex/search-tests suite against the biggy account, 4 containers, parallel. Requires repository secrets APP_KEY, APP_TOKEN, RECORD_KEY.

Verified Commands

make dev          # yarn install (root + node) + vtex setup
make lint         # cd node && yarn lint (tsc --noEmit — type-check)
make test         # cd node && yarn test (jest 29 + ts-jest)
make coverage     # cd node && yarn test --coverage (60% threshold)
make check        # lint + test (matches root `yarn verify`)
make link         # vtex link (uses active VTEX account/workspace)
make run          # alias for make link

Root yarn scripts: yarn lint, yarn format, yarn test, yarn verify (lint + test).

Expected Skills

• vtex-io-cli · vtex-io-app-structure · vtex-io-service-apps · vtex-io-graphql-api
• specification + implementing (vtex-agent-skills) for the SDD Lite workflow
• For SDD Full work, use the spec-kit pipeline against the parent Specs repo (is-io-specs/.specify/)

Expected MCPs

• GitHub MCP — cross-repo references (especially vtex.search-graphql for schema changes, vtex.intelligent-search-api for backend, vtex/search-tests for Cypress), issues, PRs.
• Atlassian MCP — Jira/Confluence context.

Multi-repo Specs

Part of the is-io-specs multi-repo workspace. SpecKit artifacts (.specify/memory/constitution.md, docs/scope_of_work/, specs/<feature>/) live at the parent aggregator. This repo intentionally has no local .specify/. See the Multi-repo spec-kit extension.

Autonomy Limits

Toolbelt and platform

• Never run vtex link, vtex publish, vtex deploy, workspace promotion, or any account/workspace-changing Toolbelt command without explicit confirmation.
• Never modify manifest.json version directly — use vtex release <patch|minor|major> stable.
• Never modify node/typings/ — regenerated by vtex setup --typings --ignore-linked.
• Ask before adding/removing builders or policies in manifest.json.

Schema contract

• The schema is owned by vtex.search-graphql, not this repo. Adding a new field requires a coordinated PR there first. Resolver additions here will fail at runtime if the field is not in the schema.
• Do not change field shapes of Product, SKU, Brand, Category, Facet, Offer, AssemblyOption without coordinated PRs in vtex.search-result (PLP) and any private storefront consumers.
• Schema directives (@cacheControl, @withSegment) are part of the contract. Removing or changing semantics affects caching and segment isolation.

Resolver constraints

• Cache headers are emitted via the @cacheControl directive on schema fields, not from resolver code. If you need a non-standard TTL, change the schema in vtex.search-graphql, not the resolver.
• Segment isolation: @withSegment ensures the resolver sees the shopper's segment context. Do not bypass it for fields that vary per-shopper.
• @gocommerce/utils branches behavior for go-commerce stores. Always go through the existing helpers; do not gate by account name.

Endpoint switching

• shouldUseNewPDPEndpoint is a per-account flag. Adding a new flag requires updating manifest.json:settingsSchema and the corresponding read sites. PLP product search/facets are intsch-only (no PLP flag).
• Never call intelligentSearchApi and the legacy search client for the same field — pick one based on settings, or you'll double-bill and double-cache.

Observability

• Log via ctx.vtex.logger with structured payloads. ctx.vtex.logger.info({ message, ... }), not bare strings.
• Coverage is collected by Jest (coverageProvider: 'v8') into node/coverage/. The directory is gitignored; SonarQube ingestion is wired via DK CI.

Cypress autonomy

• The Cypress job runs against the biggy account. Never point it at a real customer account without explicit coordination — Cypress runs may issue real cart/order operations.
• Repository secrets APP_KEY, APP_TOKEN, RECORD_KEY must be set in GitHub before the Cypress job will work in a forked PR.