chore(dev): Support Claude Code cloud (remote) sessions (#22573)

Enables this repo to run in Claude Code cloud (remote) sessions by
committing the bootstrap needed to install and build the monorepo on
session start.

- `scripts/claude-cloud-setup.sh` — runs `yarn install --ignore-engines
--frozen-lockfile` (matching CI) then `yarn build:dev`, with
`VOLTA_FEATURE_PNPM=1` exported.
- `.claude/settings.json` — a `SessionStart` hook runs that script,
gated to cloud sessions via `CLAUDE_CODE_REMOTE=true` so local sessions
are untouched.
- `.claude/CLOUD.md` — documents the one-time per-environment settings
that can't be committed (setup script, network access, env vars).

The hook runs install + build on **every** cloud session rather than
depending on the cached environment-creation setup script, because the
working branch changes constantly and a cached build would be stale.
Repeated runs stay cheap: a frozen-lockfile install is a no-op when
`node_modules` is warm, and Nx only rebuilds packages whose inputs
changed.

`build:dev` (transpile + types) is used instead of the full production
`yarn build` — enough for editing and unit tests, and faster on each
session.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mydea

.claude/CLOUD.md

@@ -0,0 +1,27 @@
+# Running this repo in Claude Code cloud (remote sessions)
+
+Most of the setup is committed to the repo and works automatically:
+
+- **`scripts/claude-cloud-setup.sh`** — bootstrap: `yarn install --frozen-lockfile` + `yarn build:dev`. Runs **every** session so the checkout is always built against the current branch. Repeated runs are cheap (frozen install is a no-op when warm; Nx only rebuilds changed packages).
+- **`.claude/settings.json`** — a `SessionStart` hook runs that script, but only in cloud sessions (`CLAUDE_CODE_REMOTE=true`). Local sessions are unaffected.
+
+## One-time environment setup (done in the `claude.ai/code` UI)
+
+These cannot live in the repo and must be set once per environment:
+
+1. **Setup script** — install the language runtime the sandbox lacks, e.g.:
+
+   ```bash
+   bash scripts/claude-cloud-setup.sh
+   ```
+
+   Do not rely on the cached result for freshness: install + build re-run on every session via the SessionStart hook, because the working branch changes constantly. This runs the same script mostly to warm the caches (node_modules, Nx) so the first real session is fast.
+
+2. **Network access:** `Trusted` (default) is sufficient — it already allows the npm registry and GitHub, which is all the install needs.
+
+3. **Environment variables:** none required for build/test. Add any Sentry DSNs or tokens here only if you intend to run E2E/integration suites that need them (visible to anyone who can edit the environment — do not put long-lived secrets here).
+
+## Notes
+
+- Node/Yarn versions come from `package.json` (Volta locally). In the cloud we use the sandbox runtime and pass `--ignore-engines`, matching CI.
+- The full production `yarn build` is not run at startup; `build:dev` (transpile + types) is enough for editing and running unit tests. Run `yarn build` manually if you need bundles.

.claude/settings.json

@@ -1,5 +1,18 @@
 {
   "env": { "ENABLE_LSP_TOOL": "1" },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then bash \"$CLAUDE_PROJECT_DIR\"/scripts/claude-cloud-setup.sh; fi"
+          }
+        ]
+      }
+    ]
+  },
   "permissions": {
     "allow": [
       "Bash(find:*)",

scripts/claude-cloud-setup.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# Bootstrap the Sentry JavaScript monorepo for a Claude Code cloud session.
+#
+# Wired as the repo's SessionStart hook (see .claude/settings.json), gated to
+# cloud sessions. It runs on every session so the checkout is always installed
+# and built against the *current* branch -- the code changes constantly, so a
+# build cached at environment-creation time would be stale. Repeated runs are
+# cheap: a frozen-lockfile install is a no-op when node_modules is warm, and Nx
+# only rebuilds packages whose inputs actually changed.
+#
+# Node/Yarn versions come from `package.json` (managed by Volta locally); in the
+# cloud we rely on whatever runtime the sandbox provides and pass --ignore-engines
+# to match CI (.github/actions/install-dependencies).
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Required by the repo's package-manager setup (some workspaces use pnpm via Volta).
+export VOLTA_FEATURE_PNPM=1
+
+echo "node: $(node --version 2>/dev/null || echo 'not found')"
+echo "yarn: $(yarn --version 2>/dev/null || echo 'not found')"
+
+echo "Installing dependencies (yarn install --frozen-lockfile)..."
+yarn install --ignore-engines --frozen-lockfile
+
+echo "Building packages (yarn build:dev)..."
+yarn build:dev
+
+echo "Cloud setup complete."