Merge branch 'main' into alwx/ci/sample-app-production-only-builds

Author: alwx

.agents/skills/.gitkeep

@@ -0,0 +1,121 @@
+---
+name: code-guidelines
+description: Enforce Sentry React Native SDK code guidelines for implementation, refactoring, and review. Use when implementing features, adding functionality, refactoring, reviewing code, designing APIs, changing the public API surface (the `packages/core/src/js/index.ts` barrel), handling breaking changes, deprecating options, writing integrations, touching the JS↔native bridge, or making architecture decisions in this yarn-workspaces monorepo.
+---
+
+Apply these guidelines to all new and modified code in `packages/core`. Existing code may not follow these conventions — do not refactor it unless asked.
+
+This SDK spans **four surfaces**: TypeScript/JS (`packages/core/src/js/`), Android (Java/Kotlin, `packages/core/android/`), iOS (ObjC/Swift, `packages/core/ios/`), and the **JS↔native bridge** (`RNSentry` TurboModule / legacy NativeModule) that connects them. Read the `AGENTS.md` for the surface you're touching — root, `packages/core/`, `packages/core/android/`, `packages/core/ios/` — before writing. The bridge is where most SDK-specific bugs live; the deep guidance for it is in [`packages/core/AGENTS.md`](../../../packages/core/AGENTS.md).
+
+For non-trivial work — a new feature or integration, a public barrel-file change, or a change that crosses the native bridge — load the **design-first** skill to shape the modules and seams before writing code. When writing or modifying tests, also load the **test-guidelines** skill.
+
+## SDK Development Rules
+
+### Integrations
+
+SDK features are packaged as **integration factory functions** that return an `Integration` (from `@sentry/core`). See `src/js/integrations/` for the canonical shape (e.g. `nativelinkederrors.ts`):
+
+```typescript
+const INTEGRATION_NAME = 'MyFeature';
+
+export const myFeatureIntegration = (options: Partial<MyOptions> = {}): Integration => {
+  return {
+    name: INTEGRATION_NAME,
+    setupOnce: () => { /* one-time global side effects, if any */ },
+    setup: (client: Client) => { /* per-client wiring */ },
+    processEvent: (event, hint, client) => { /* enrich/drop */ return event; },
+  };
+};
+```
+
+- **Check prerequisites and feature flags early** — if the feature is disabled or the native module is missing, log via `debug` and return without wiring anything up.
+- Name the integration with a module-level `INTEGRATION_NAME` constant; don't inline the string.
+- Integrations should be **order-independent**. If yours must run before/after another, reconsider the design.
+- Register default integrations in `src/js/integrations/default.ts`; keep an integration's options and defaults with the integration, not scattered across `options.ts`.
+- Clean up anything global (listeners, timers) — an integration that arms a timer or subscribes to an emitter must have a path that tears it down.
+
+### Native Bridge (JS side)
+
+Every call into native goes through the `NATIVE` wrapper (`src/js/wrapper.ts`) / `RNSentry` TurboModule. Rules:
+
+- **Guard on availability.** If `enableNative` is false or the module isn't linked, degrade gracefully — return a safe fallback, never throw into user code.
+- **Never let a native rejection escape.** Wrap bridge calls; log via `debug` and return a fallback. A thrown promise rejection from the bridge becomes an unhandled rejection in the host app.
+- **Everything crossing the bridge must be serializable** — plain JSON (no functions, class instances, `undefined` holes, circular refs, or `BigInt`). Both the New Architecture (JSI/TurboModule codegen) and the legacy bridge serialize payloads; a non-serializable value is silently dropped or throws on the native side. Verify `toJSON`/normalization round-trips.
+- **Do not wrap `RNSentry`'s own scope-sync methods** (`setTag`, `setContext`, `addBreadcrumb`, `setUser`, `captureEnvelope`, …). Wrapping them recurses — see the `RNSENTRY_SKIP` / `ignoreTurboModules` notes in `packages/core/AGENTS.md`.
+- In this hot path, `logger` from `@sentry/core` is the **Logs API** (emits log events), not the debug logger. Use **`debug`** for diagnostics — see the TurboModule section of `packages/core/AGENTS.md`.
+
+### Native Bridge (native side)
+
+- **Android** (`packages/core/android/`): resolve/reject the `Promise` on every path; never leak it. Release JNI local refs; don't let a native exception cross back into the bridge uncaught. Old vs new arch code lives in `src/oldarch/` and `src/newarch/`; shared code in `src/main/`.
+- **iOS** (`packages/core/ios/`): prefix classes `RNSentry`; use nullability annotations; watch for retain cycles in blocks (capture `weakSelf`). Route hybrid-SDK access through `RNSentryInternal` (see `packages/core/ios/AGENTS.md`), not deprecated `PrivateSentrySDKOnly`.
+- A native exception must **never crash the host app** — catch at the bridge boundary and reject/log instead.
+
+### Codegen (New Architecture)
+
+The bridge spec is codegen'd. `src/js/NativeRNSentry.ts` is the `TurboModule` spec; `RNSentryReplayMask*NativeComponent.ts` are Fabric component specs.
+
+- Codegen only supports a **restricted type vocabulary** — primitives, `Object` (untyped map), arrays, and nullable via `?`. No unions of literals, no generics, no `Record<K,V>` with non-string keys. If a method's shape can't be expressed, pass an `Object` and validate/parse on the native side.
+- Any change to a `Native*.ts` spec is a **bridge ABI change**: it must land in lockstep across the JS spec, `ios/RNSentry.mm`, and the Android `RNSentryModuleImpl`, and stay backward-compatible with older native binaries a user may have cached. Treat it like a public API change.
+
+### Usage tracking & SDK metadata
+
+The event's [SDK interface](https://develop.sentry.dev/sdk/data-model/event-payloads/sdk/) carries `sdk.integrations`, `sdk.packages`, and an optional `sdk.features` list; the spec says a feature should be reported through **either** an integration **or** the `features` list, not both. RN takes the *integrations* route: unlike sentry-dart (which populates `sdk.features` via an explicit `addFeature` / `SentryFeatures` API), RN's `@sentry/core` reports usage only through `event.sdk.integrations` and does **not** populate `sdk.features`. So usage is reported implicitly:
+
+- An **installed integration is auto-reported by its `name`** — `@sentry/core` collects the names of installed integrations into `event.sdk.integrations`. So the practical rule is: give the integration a stable, correct `INTEGRATION_NAME`, and register it (a default in `integrations/default.ts`, or `client.addIntegration(...)`) — that registration *is* the usage signal. A feature that runs without a registered, named integration is invisible to usage tracking.
+- **SDK identity/packages** come from `src/js/version.ts` (`SDK_NAME`, `SDK_PACKAGE_NAME`, `SDK_VERSION`) surfaced by `integrations/sdkinfo.ts`, which also appends the native SDK package — not the place to register feature usage.
+- Do **not** confuse this with `addFeatureFlag` on the native module (`wrapper.ts` / `NativeRNSentry.ts`) — that is the user-facing **feature-flags** product, unrelated to SDK usage tracking.
+
+When adding something you want measured, make sure it lands as a named, registered integration rather than a bare side effect.
+
+### Logging
+
+- **`debug`** (from `@sentry/core`) is the internal diagnostic logger — use it for all SDK diagnostics. It is tree-shaken / gated so it stays quiet in production.
+- **`logger`** (from `@sentry/core`) is the **Logs API** — it emits user-visible log *events*. Never use it for internal diagnostics, and never in a hot path (see bridge rules above).
+- Log at the right level: `debug` for lifecycle/config, `warn` for recoverable/degraded paths (native module missing, option ignored), `error` for failures that affect SDK behavior.
+
+### Privacy (PII)
+
+- **Never collect PII without gating on `options.sendDefaultPii`.** This covers IP inference, device identifiers, deep-link URLs, navigation params, request/response bodies, and user-supplied context.
+- Flag any change that could place user data into breadcrumbs, event payloads, span attributes, or logs for review.
+- Deliberate exceptions exist and must be documented where they live (e.g. TurboModule module/method names are app-defined identifiers sent regardless of `sendDefaultPii` — see `packages/core/AGENTS.md` "Privacy"). Don't add new always-on data collection without that justification.
+
+### Breaking changes
+
+- The public API is the `src/js/index.ts` barrel plus every exported option in `options.ts`. Its shape is captured in the API report (`packages/core/etc/sentry-react-native.api.md`); regenerate with `yarn api-report` and check with `yarn api-report:check`.
+- Removing or changing the signature/behavior of an exported symbol or option is a **semver-major breaking change**. Prefer **deprecation with a migration path** (`@deprecated` JSDoc + a working shim) over immediate removal.
+- Bridge/ABI changes (see Codegen) are breaking even when the JS surface looks unchanged — an app can ship new JS against an older cached native binary.
+
+### Adding dependencies
+
+When adding or changing any third-party reference — an npm dependency, a `.vscode/extensions.json` recommendation, a GitHub Action (`uses:`), or a native dependency (Podfile / Gemfile / Gradle) — verify it is published by its legitimate owner **before** referencing it. The tool being real is not enough: the *namespace* must be one the project trusts. Prefer Sentry's own scope/org (`@sentry/*`, `getsentry/*`), then the artifact's documented official publisher, and pin to an exact version / full commit SHA rather than a floating tag. Treat an unscoped or unfamiliar-publisher name as a supply-chain risk until proven otherwise — a claimable namespace lets an attacker ship code to every contributor. Provenance is necessary but not sufficient: a legitimate owner's account or CI can be compromised and ship a malicious *version*, so pin to an immutable ref (lockfile integrity hash / full SHA) and check advisories for that specific version, not just the publisher. See [references/supply-chain.md](references/supply-chain.md) for the surface-by-surface checklist and verification commands.
+
+## File Organization
+
+**Group by feature, not by type.** A processor or helper a feature owns lives with that feature (the TurboModule files sit together as `turbomodule/` + `integrations/turboModuleContext*.ts`). The `integrations/` directory is a **type-bucket** — it collects things that share the `Integration` type. Don't treat "it's an integration" as the whole home for a cohesive subsystem; keep the subsystem's own logic together and let the integration file be thin wiring.
+
+Native code lives under `packages/core/android/` and `packages/core/ios/` and is reached only through the `NATIVE` wrapper seam — features *call* the bridge, they don't embed native code.
+
+*Where* a given piece goes is a locality judgment — see **design-first**.
+
+## TypeScript & API style
+
+Shape the public surface deliberately (see **design-first** for module shape). In an SDK these matter more than in app code:
+
+- **Private by default.** Don't export a symbol from the barrel unless it's genuinely part of the SDK's API — every export is a breaking-change liability and shows up in the API report.
+- **Explicit types on public functions** — annotate parameters and return types; don't rely on inference across the API boundary.
+- **`unknown` over `any`.** Narrow with type guards; `any` disables the checker exactly where SDK robustness matters.
+- **Prefer `interface` for object shapes**; use `type` for unions/mapped types.
+- **Optional chaining / nullish coalescing** (`?.`, `??`) over hand-rolled truthiness — but remember `??` and `?.` treat `0`/`''`/`false` correctly where `||` doesn't.
+- **Re-throw, don't wrap-and-rethrow.** Preserve the original error and its stack; when adding context, attach a `cause` rather than replacing the error — stack-trace fidelity is the product.
+- **No cross-boundary deep imports.** Import from `@sentry/core` / `@sentry/browser` public entry points, not their internal paths; keep RN-internal imports within `src/js`.
+
+Style enforced by ESLint/oxlint/Prettier (single quotes, trailing commas, 120 cols, arrow-paren avoidance, import ordering) is **not** restated here — don't flag what `yarn lint` / `yarn fix` already handles. See `packages/core/AGENTS.md` for the list.
+
+## Documentation comments
+
+Prefer self-documenting code; comment for the two cases that earn it:
+
+- **Public APIs** — JSDoc for every exported symbol and option, written for users who can't see the implementation.
+- **Non-obvious *why*** — workarounds, ordering constraints, native-bridge quirks, RN-version differences. The reasoning, not the play-by-play.
+
+Don't narrate obvious behavior or restate the code. Use `@deprecated`, `@internal`, and `@hidden` deliberately — `@internal`/`@hidden` keep a symbol out of the generated API surface even when it must be exported for cross-file use.

.agents/skills/code-guidelines/SKILL.md

@@ -0,0 +1,58 @@
+# Native bridge & codegen gotchas
+
+Reference for the JS↔native seam. Loaded by **code-guidelines** and cited by **review**'s Correctness axis. The living, file-level detail is in [`packages/core/AGENTS.md`](../../../../packages/core/AGENTS.md) — this doc is the durable checklist.
+
+## The two architectures
+
+React Native ships two module systems and this SDK supports both:
+
+- **New Architecture** — JSI / TurboModules (JS spec in `src/js/NativeRNSentry.ts`) + Fabric components. Codegen generates the C++/Java/ObjC glue from the TS spec. Native side: `ios/RNSentry.mm`, `android/src/newarch/`.
+- **Old Architecture** — the async bridge, `NativeModules.RNSentry`. Native side: `android/src/oldarch/`. Legacy auto-instrumentation of third-party modules is opt-in (`enableLegacyNativeModules`) and best-effort.
+
+A change is only "done" when it works on **both** archs. `Platform`/arch branches (`isTurboModuleEnabled()`, `isFabricEnabled()`) are the usual seams — test both branches.
+
+## Codegen type vocabulary (New Arch)
+
+Codegen only understands a narrow set of types in a `TurboModule` / component spec:
+
+- Primitives: `boolean`, `number`, `string`
+- `Object` — an **untyped** map (opaque `NSDictionary`/`ReadableMap`); the shape is *not* checked
+- Arrays of the above
+- Nullability via `?` on the property/param
+- `Promise<T>` return
+
+Not supported: literal unions, enums, generics, `Record<K, V>`, tuples, discriminated unions, function-valued props (except event callbacks on components), `undefined` as a value. If a method needs a richer shape, declare the param as `Object` and validate/normalize on the native side — the type system will *not* catch a mismatch for you.
+
+## Serialization across the bridge
+
+Everything crossing the bridge is serialized to a JSON-ish value:
+
+- **No** functions, class instances, `Symbol`, `BigInt`, `undefined` holes, circular references, or `Map`/`Set`. These are dropped, throw, or arrive mangled.
+- `undefined` object properties do not survive; use `null` or omit the key.
+- Large payloads (envelopes, screenshots, replay frames) cross as base64/byte arrays — mind the copy cost and size limits.
+- Always confirm the value **round-trips**: what you send is what native receives and what comes back parses. Add a serialization test for any new payload shape.
+
+## ABI / versioning
+
+- Any edit to `src/js/NativeRNSentry.ts` (or a `*NativeComponent.ts` spec) is a **bridge ABI change**. It must land in lockstep in the JS spec, `ios/RNSentry.mm`, and `android/.../RNSentryModuleImpl`, and must be **backward compatible**: a user can ship new JS against an older cached native binary. New methods are safe; changing an existing method's signature/semantics is breaking.
+- Treat spec changes like public-API changes — they belong in the changelog and may be semver-major.
+
+## Memory & crash safety
+
+- **Android:** release JNI local refs; resolve *or* reject every `Promise` on every path (a leaked Promise hangs the JS caller). Never let a native exception propagate uncaught across the bridge.
+- **iOS:** avoid retain cycles in blocks (`__weak` self); honor nullability annotations; route hybrid-SDK access through `RNSentryInternal`.
+- A native crash caused by the SDK crashes the **host app** — the highest-severity failure this SDK can cause. Catch at the bridge boundary; degrade, don't crash.
+
+## Privacy at the bridge
+
+Data flowing from native (device context, breadcrumbs, module/method names, deep-link URLs) must respect `sendDefaultPii`. Any always-on collection needs an explicit, documented justification (see `packages/core/AGENTS.md` "Privacy" for the TurboModule exception and why it exists).
+
+## Quick checklist for a bridge change
+
+- [ ] Works on New **and** Old Architecture (both branches exercised)
+- [ ] Spec change (if any) landed in JS + iOS + Android in lockstep, backward-compatible
+- [ ] Payload is codegen-expressible or validated as `Object` on the native side
+- [ ] Payload round-trips (serialization test added)
+- [ ] Native failure is caught at the boundary — no host-app crash, no leaked Promise, no leaked native memory
+- [ ] PII gated on `sendDefaultPii` (or documented exception)
+- [ ] Graceful fallback when `enableNative` is false / module not linked