feat: release 4.6.0 (graduate dev → main)

.github/workflows/back-merge.yml

@@ -106,8 +106,13 @@ jobs:
         if: steps.prep.outputs.skip == 'false'
         run: |
           pnpm i
+          # core#generate shells out to the CLI binary, which must be compiled
+          # first (see turbo.json: @faststore/core#generate → @faststore/cli#build).
+          # api must be built before the CLI because generate-types imports
+          # GraphqlVtexSchema from @faststore/api at runtime.
           pnpm --filter @faststore/api build
           pnpm --filter @faststore/api generate
+          pnpm --filter @faststore/cli build
           pnpm --filter @faststore/core generate
           git add -A
 

CHANGELOG.md

@@ -3,10 +3,87 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.5.1](https://github.com/vtex/faststore/compare/v4.5.1-dev.2...v4.5.1) (2026-08-11)
+# [4.6.0-dev.6](https://github.com/vtex/faststore/compare/v4.6.0-dev.5...v4.6.0-dev.6) (2026-08-14)
+
+### Bug Fixes
+
+- resolve node_modules bins when running scripts inside .faststore ([#3440](https://github.com/vtex/faststore/issues/3440)) ([2bf174a](https://github.com/vtex/faststore/commit/2bf174a7295d106354d97d7ca2c161ed706cff9a)), closes [#3439](https://github.com/vtex/faststore/issues/3439) [#3419](https://github.com/vtex/faststore/issues/3419)
+
+# [4.6.0-dev.5](https://github.com/vtex/faststore/compare/v4.6.0-dev.4...v4.6.0-dev.5) (2026-08-13)
+
+### Bug Fixes
+
+- **core:** add experimental.revalidate404 and skip PLP query on notFound ([855a3ee](https://github.com/vtex/faststore/commit/855a3ee2e3393ee092d4b261ad83a8757289e132))
+- **core:** revalidate ISR cache for notFound PDP/PLP paths ([1d1015e](https://github.com/vtex/faststore/commit/1d1015e8874d794c5f54e572afc3c676fabce69c))
+
+# [4.6.0-dev.4](https://github.com/vtex/faststore/compare/v4.6.0-dev.3...v4.6.0-dev.4) (2026-08-12)
+
+### Bug Fixes
+
+- custom GraphQL typeDefs silently ignored on Windows ([#3419](https://github.com/vtex/faststore/issues/3419)) ([bdeb6a7](https://github.com/vtex/faststore/commit/bdeb6a757c44dda24b96cffc73d34652de165adf))
+
+# [4.6.0-dev.3](https://github.com/vtex/faststore/compare/v4.6.0-dev.2...v4.6.0-dev.3) (2026-08-12)
+
+**Note:** Version bump only for package faststore
+
+# [4.6.0-dev.2](https://github.com/vtex/faststore/compare/v4.6.0-dev.1...v4.6.0-dev.2) (2026-08-12)
+
+### Bug Fixes
+
+- **api:** address Sonar and harden session sales-channel sync ([5f6e8e9](https://github.com/vtex/faststore/commit/5f6e8e909def75f60c24cdaffae9303ed2c0a052))
+- **api:** address Sonar findings in validateCart and orderForm URL ([3211231](https://github.com/vtex/faststore/commit/321123179d3e5789fb7730ef94c8f2f0d8b878b1))
+- **api:** keep orderForm sales channel after stale validateCart sync ([09b051b](https://github.com/vtex/faststore/commit/09b051b80aaff7183adf7f5e86aece438bcd38f0))
+- **api:** preserve orderForm sales channel in validateCart ([2336cda](https://github.com/vtex/faststore/commit/2336cda2c95970850dd0d29c1c18043ca8c9078a))
+- **api:** sync adopted orderForm sales channel into session ([8943da7](https://github.com/vtex/faststore/commit/8943da7821f8abec08a39b7907a258bf156b05ee))
+
+### Reverts
+
+- Revert "docs(api): add before/after screenshots for validateCart PR" ([eaaf032](https://github.com/vtex/faststore/commit/eaaf0323b004988d849679ba19ff61ab75dd0875))
+
+# [4.6.0-dev.1](https://github.com/vtex/faststore/compare/v4.6.0-dev.0...v4.6.0-dev.1) (2026-08-11)
+
+## [4.5.1](https://github.com/vtex/faststore/compare/v4.5.1-dev.4...v4.5.1) (2026-08-11)
+
+### Bug Fixes
+
+- **core:** address scroll restoration review feedback ([a5fe6a3](https://github.com/vtex/faststore/commit/a5fe6a35c54e6095f81c7995a815ce6ef3b4dd4e))
+- **core:** align beforePopState callback with NextHistoryState ([10719e5](https://github.com/vtex/faststore/commit/10719e5eca199385d9fe18bdd6d7da290716a1d5))
+- **core:** compare window to undefined directly for Sonar ([bf05a54](https://github.com/vtex/faststore/commit/bf05a54bb014d120b7bdc95ff7c01a4e9b35b485))
+- **core:** harden scroll restore path matching and hydration-safe heights ([34efa6b](https://github.com/vtex/faststore/commit/34efa6bda7549895a4531277c2fe55bd6bbe98a7))
+- **core:** hash gallery height keys to avoid truncation collisions ([9e98043](https://github.com/vtex/faststore/commit/9e980438d74e457fa33aa77900438339463a078c))
+- **core:** prevent IS redirect hang and improve scroll restoration ([5f30778](https://github.com/vtex/faststore/commit/5f30778161eec2e4381b3fe971479dd7cbe53b08))
+- **core:** reset infinite scroll on forward listing navigations ([249226a](https://github.com/vtex/faststore/commit/249226a3acbe4cb26d687cf962125b2593d5949e))
+- **core:** resolve Sonar new-code smells for scroll restoration ([59b41ed](https://github.com/vtex/faststore/commit/59b41ed1d2a30ba693726b19895a0279eb1ba464))
+- **core:** restore PLP infinite-scroll pages on back navigation ([92b2efa](https://github.com/vtex/faststore/commit/92b2efa1d4d0895a10b5a0e71a4d9bf37cae1686))
+- **core:** resync gallery height lock when children change ([5058089](https://github.com/vtex/faststore/commit/50580898d97baf800b97c8a876f7967529859c61))
+- **core:** satisfy Sonar on gallery height key hash ([3a6ce47](https://github.com/vtex/faststore/commit/3a6ce47485c26be75d6d76906df3af64c9e34fd6))
+- **core:** type scroll restore paint timer for DOM/Node setTimeout ([940c903](https://github.com/vtex/faststore/commit/940c90376f8d2eb77665e73a6fb0ea53c9786c8e))
+- **core:** use replaceAll for infinite-scroll session key ([4f52048](https://github.com/vtex/faststore/commit/4f520482a9ba9661782fcf25a286b8f2e6c6b922))
+
+# [4.6.0-dev.0](https://github.com/vtex/faststore/compare/v4.5.1-dev.4...v4.6.0-dev.0) (2026-08-11)
+
+### Features
+
+- removing vtex/diagnostics-nodejs ([#3389](https://github.com/vtex/faststore/issues/3389)) ([74e2d50](https://github.com/vtex/faststore/commit/74e2d503a44903929b90af7701956536690d4e41))
+
+## [4.5.1-dev.4](https://github.com/vtex/faststore/compare/v4.5.1-dev.3...v4.5.1-dev.4) (2026-08-10)
 
 ### Bug Fixes
 
+- restore account, path, port arg order on cli dev command ([#3439](https://github.com/vtex/faststore/issues/3439)) ([b13e834](https://github.com/vtex/faststore/commit/b13e8341539fb8108c35a63f26218c4671d308f8)), closes [#3111](https://github.com/vtex/faststore/issues/3111) [#2491](https://github.com/vtex/faststore/issues/2491) [#2491](https://github.com/vtex/faststore/issues/2491) [#3111](https://github.com/vtex/faststore/issues/3111)
+
+## [4.5.1-dev.3](https://github.com/vtex/faststore/compare/v4.5.1-dev.2...v4.5.1-dev.3) (2026-08-10)
+
+### Bug Fixes
+
+- **core:** add twitter card meta tag to default next seo config ([720f3e6](https://github.com/vtex/faststore/commit/720f3e6d04ef523f2fcf0e146c3741b7e5af70fa))
+- **core:** add twittermeta tags validaton for tests ([c8f5872](https://github.com/vtex/faststore/commit/c8f5872e42b69ddae5b2abfa0e8d3140e2bc7163))
+- **core:** lint error ([d07460f](https://github.com/vtex/faststore/commit/d07460f890ba712c9aecbec25bda5de96bf3e4ef))
+- **core:** remove duplicated twitter meta tag ([f388288](https://github.com/vtex/faststore/commit/f388288731ff75fceedba3cd7449ef1088b0b0c2))
+- **metaTags:** add twitter meta tags to nextSeo ([9c2439b](https://github.com/vtex/faststore/commit/9c2439b4a668dd81b7bfe5bdc44df575725067ec))
+
+## [4.5.1](https://github.com/vtex/faststore/compare/v4.5.1-dev.2...v4.5.1) (2026-08-11)
+
 - **core:** address scroll restoration review feedback ([a5fe6a3](https://github.com/vtex/faststore/commit/a5fe6a35c54e6095f81c7995a815ce6ef3b4dd4e))
 - **core:** align beforePopState callback with NextHistoryState ([10719e5](https://github.com/vtex/faststore/commit/10719e5eca199385d9fe18bdd6d7da290716a1d5))
 - **core:** compare window to undefined directly for Sonar ([bf05a54](https://github.com/vtex/faststore/commit/bf05a54bb014d120b7bdc95ff7c01a4e9b35b485))

README.md

@@ -62,7 +62,7 @@ These packages are part of the monorepo but are not intended for direct use by s
 | Package | Description |
 | :--- | :--- |
 | `@faststore/lighthouse` | Generates Lighthouse CI configurations for automated performance audits and quality gates. |
-| `@faststore/diagnostics` | OpenTelemetry tracing and observability for monitoring application performance. |
+| `@faststore/diagnostics` | OpenTelemetry tracing and logging for monitoring application performance. |
 | `@faststore/storybook` | Isolated environment for developing and documenting UI components (not published). |
 
 ## License

docs/observability.md

@@ -0,0 +1,51 @@
+# Observability
+
+FastStore uses OpenTelemetry for server-side logs and traces, exported over OTLP
+gRPC to VTEX collectors. The SDK is started by `@faststore/diagnostics` from the
+Next.js instrumentation hook in `@faststore/core`.
+
+## Enabling
+
+Telemetry is **off until the feature is released**. It is gated by two hardcoded
+flags rather than by store configuration, so a store cannot turn it on:
+
+| Flag | File | Controls |
+| :--- | :--- | :--- |
+| `instrumentationEnabled` | [`packages/core/src/instrumentation.ts`](../packages/core/src/instrumentation.ts) | Starting the OTel SDK, and therefore whether `logger()` emits anything |
+| `OTEL_ENABLED` | [`packages/core/src/server/options.ts`](../packages/core/src/server/options.ts) | The per-request root span in `execute()` and the resolver spans from `@faststore/api` |
+
+Flip both to `true` to exercise the pipeline locally. `logger()` is a no-op
+until the SDK has started, so `OTEL_ENABLED` on its own emits neither traces nor
+logs.
+
+## Configuration
+
+Endpoints and sampling default to the VTEX collectors and can be overridden with
+environment variables — see
+[`packages/diagnostics/src/globals.ts`](../packages/diagnostics/src/globals.ts):
+
+| Variable | Description |
+| :--- | :--- |
+| `OTLP_TRACES_ENDPOINT` | OTLP gRPC endpoint for traces |
+| `OTLP_LOGGER_ENDPOINT` | OTLP gRPC endpoint for logs |
+| `OTLP_TRACES_SAMPLE_RATE` | Fraction of traces exported outside development (default `0.3`) |
+
+To send logs to the development collector, set `OTLP_LOGGER_ENDPOINT` to
+`developer-logs.opentelemetry-collector.vtex.systems:80`.
+
+## Logs
+
+Search in the [Grafana app](https://grafana.vtex.com/explore) by attribute:
+
+- `vtex.account.name:<account>` — for example `vtex.account.name:storeframework`
+- `vtex.application.id:faststore`
+
+> Development logs are queried at `victoria-logs-developer`, production at `victoria-logs-main`.
+
+## Traces
+
+Connect to the VPN and open the [SigNoz app](https://signoz-traces.vtex.systems/home),
+then search for traces carrying:
+
+- `@faststore_account_name: <account>`
+- `@faststore_environment: production` or `@faststore_environment: development`

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.5.1",
+  "version": "4.6.0-dev.6",
   "npmClient": "pnpm",
   "command": {
     "publish": {

packages/api/CHANGELOG.md

@@ -3,6 +3,50 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.6.0-dev.6](https://github.com/vtex/faststore/compare/v4.6.0-dev.5...v4.6.0-dev.6) (2026-08-14)
+
+**Note:** Version bump only for package @faststore/api
+
+# [4.6.0-dev.5](https://github.com/vtex/faststore/compare/v4.6.0-dev.4...v4.6.0-dev.5) (2026-08-13)
+
+**Note:** Version bump only for package @faststore/api
+
+# [4.6.0-dev.4](https://github.com/vtex/faststore/compare/v4.6.0-dev.3...v4.6.0-dev.4) (2026-08-12)
+
+**Note:** Version bump only for package @faststore/api
+
+# [4.6.0-dev.3](https://github.com/vtex/faststore/compare/v4.6.0-dev.2...v4.6.0-dev.3) (2026-08-12)
+
+**Note:** Version bump only for package @faststore/api
+
+# [4.6.0-dev.2](https://github.com/vtex/faststore/compare/v4.6.0-dev.1...v4.6.0-dev.2) (2026-08-12)
+
+### Bug Fixes
+
+- **api:** address Sonar and harden session sales-channel sync ([5f6e8e9](https://github.com/vtex/faststore/commit/5f6e8e909def75f60c24cdaffae9303ed2c0a052))
+- **api:** address Sonar findings in validateCart and orderForm URL ([3211231](https://github.com/vtex/faststore/commit/321123179d3e5789fb7730ef94c8f2f0d8b878b1))
+- **api:** keep orderForm sales channel after stale validateCart sync ([09b051b](https://github.com/vtex/faststore/commit/09b051b80aaff7183adf7f5e86aece438bcd38f0))
+- **api:** preserve orderForm sales channel in validateCart ([2336cda](https://github.com/vtex/faststore/commit/2336cda2c95970850dd0d29c1c18043ca8c9078a))
+- **api:** sync adopted orderForm sales channel into session ([8943da7](https://github.com/vtex/faststore/commit/8943da7821f8abec08a39b7907a258bf156b05ee))
+
+# [4.6.0-dev.1](https://github.com/vtex/faststore/compare/v4.6.0-dev.0...v4.6.0-dev.1) (2026-08-11)
+
+## [4.5.1](https://github.com/vtex/faststore/compare/v4.5.1-dev.4...v4.5.1) (2026-08-11)
+
+**Note:** Version bump only for package @faststore/api
+
+# [4.6.0-dev.0](https://github.com/vtex/faststore/compare/v4.5.1-dev.4...v4.6.0-dev.0) (2026-08-11)
+
+### Features
+
+- removing vtex/diagnostics-nodejs ([#3389](https://github.com/vtex/faststore/issues/3389)) ([74e2d50](https://github.com/vtex/faststore/commit/74e2d503a44903929b90af7701956536690d4e41))
+
+## [4.5.1-dev.4](https://github.com/vtex/faststore/compare/v4.5.1-dev.3...v4.5.1-dev.4) (2026-08-10)
+
+**Note:** Version bump only for package @faststore/api
+
+## [4.5.1-dev.3](https://github.com/vtex/faststore/compare/v4.5.1-dev.2...v4.5.1-dev.3) (2026-08-10)
+
 ## [4.5.1](https://github.com/vtex/faststore/compare/v4.5.1-dev.2...v4.5.1) (2026-08-11)
 
 **Note:** Version bump only for package @faststore/api

packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/api",
-  "version": "4.5.1",
+  "version": "4.6.0-dev.6",
   "license": "MIT",
   "main": "dist/cjs/index.js",
   "typings": "dist/src/index.d.ts",
@@ -71,7 +71,7 @@
     "tslib": "catalog:",
     "vite": "catalog:",
     "vite-plugin-dts": "catalog:",
-    "vitest": "^4.0.7"
+    "vitest": "catalog:"
   },
   "peerDependencies": {
     "@faststore/diagnostics": "workspace:*",

packages/api/src/observability/telemetry.ts

@@ -1,9 +1,11 @@
-import { OTELAPI } from '@faststore/diagnostics'
+import { logger, OTELAPI } from '@faststore/diagnostics'
 import { name, version } from '../../package.json' with { type: 'json' }
 
+const OTELLogger = logger('@faststore/api')
+
 export const ResolverTrace = <
   TContext extends {
-    OTEL: Record<string, any>
+    OTEL_ENABLED: boolean
     account: string
     discoveryConfig: Record<string, any>
   },
@@ -12,55 +14,70 @@ export const ResolverTrace = <
   TReturn = any,
 >(
   fn: (source: TSource, vars: TVars, context: TContext, info: any) => TReturn,
-  resolverName?: string
+  resolverName = 'Unknown Graphql Resolver'
 ) => {
   return (
     source: TSource,
     vars: TVars,
     graphqlContext: TContext,
     info: any
   ): TReturn => {
-    if ((graphqlContext?.OTEL?.enabled ?? false) === false) {
+    if (!graphqlContext?.OTEL_ENABLED) {
       return fn(source, vars, graphqlContext, info)
     }
 
-    const trace = OTELAPI.trace.getTracer(name, version)
-    const activeContext = OTELAPI.propagation.extract(
-      OTELAPI.context.active(),
-      graphqlContext.OTEL
-    )
+    const span = OTELAPI.trace.getTracer('Graphql').startSpan(resolverName, {
+      kind: OTELAPI.SpanKind.INTERNAL,
+      attributes: {
+        timestamp: Date.now(),
+        '@faststore_version': version,
+        '@faststore_package_name': name,
+        '@faststore_account_name': graphqlContext.account,
+        '@faststore_environment': process.env.NODE_ENV,
+        '@faststore_resolver_parent_type': info?.parentType?.name,
+        '@faststore_resolver_field_name': info?.fieldName,
+      },
+    })
 
-    return OTELAPI.context.with(activeContext, () => {
-      const span = trace.startSpan(resolverName ?? 'Unknown Graphql Resolver', {
-        startTime: Date.now(),
-        kind: OTELAPI.SpanKind.INTERNAL,
-        attributes: {
-          timestamp: Date.now(),
-          '@faststore_version': version,
-          '@faststore_package_name': name,
-          '@faststore_account_name': graphqlContext.account,
-          '@faststore_environment': process.env.NODE_ENV,
-        },
-      })
+    const otelContext = OTELAPI.trace.setSpan(OTELAPI.context.active(), span)
 
-      if (!span) return fn(source, vars, graphqlContext, info)
-      try {
-        const returnedValue = fn(source, vars, graphqlContext, info)
+    try {
+      const result = OTELAPI.context.with(otelContext, () =>
+        fn(source, vars, graphqlContext, info)
+      )
 
-        if (!(returnedValue instanceof Promise)) {
-          span.end()
-          return returnedValue
-        }
+      if (result instanceof Promise) {
+        return result.then(
+          (value) => {
+            span.end()
 
-        return returnedValue.then((value) => {
-          span.end()
-          return value
-        }) as TReturn
-      } catch (error) {
-        span.end()
-        console.error(`Error when executing resolver: ${resolverName}`, error)
-        throw error
+            return value
+          },
+          (error) => recordResolverError(error, span, resolverName)
+        ) as TReturn
       }
-    })
+
+      span.end()
+
+      return result
+    } catch (error) {
+      return recordResolverError(error, span, resolverName)
+    }
   }
 }
+
+/** Marks the span as failed and rethrows, keeping call sites linear. */
+function recordResolverError(
+  error: unknown,
+  span: OTELAPI.Span,
+  resolverName: string
+): never {
+  span.setStatus({ code: OTELAPI.SpanStatusCode.ERROR })
+  span.recordException(error as Error)
+  span.end()
+
+  console.error(`Error at resolver: ${resolverName}: \n %o`, error)
+  OTELLogger('error', 'Error at resolver: %s\n%o', resolverName, error)
+
+  throw error
+}