[pull] main from aws-amplify:main

.github/actions/setup-samples-staging/action.yml

@@ -34,15 +34,32 @@ runs:
       env:
         BRANCH: ${{ github.ref_name }}
       run: |
-        if git ls-remote --exit-code --heads origin refs/heads/$BRANCH; then
-            # Corresponding branch on sample repo exists, check it out
-            git fetch origin $BRANCH
-            git checkout $BRANCH
-            echo "Checked out branch: $BRANCH"
-        else
-            # Corresponding branch doesn't exist, default to main
-            echo "Branch '$BRANCH' does not exist"
-        fi
+        # Retry to guard against transient git/network failures (e.g. exit code 128)
+        select_staging_branch() {
+          status=0
+          git ls-remote --exit-code --heads origin refs/heads/$BRANCH || status=$?
+          if [ "$status" -eq 0 ]; then
+              # Corresponding branch on sample repo exists, check it out
+              git fetch origin $BRANCH &&
+              git checkout $BRANCH &&
+              echo "Checked out branch: $BRANCH"
+          elif [ "$status" -eq 2 ]; then
+              # Corresponding branch doesn't exist, default to main
+              echo "Branch '$BRANCH' does not exist"
+          else
+              # Transient git failure, signal the loop below to retry
+              return 1
+          fi
+        }
+        for i in {1..3}; do
+          echo "Starting attempt $i."
+          select_staging_branch && break
+          echo "Attempt $i failed."
+          if [ "$i" -eq 3 ]; then
+            echo "::warning::Failed to check out staging branch '$BRANCH' after 3 attempts, falling back to default branch."
+          fi
+          sleep 5
+        done
 
     - name: Install
       shell: bash

.github/dependency-review/dependency-review-config.yml

@@ -32,18 +32,18 @@ allow-dependencies-licenses:
   # which means they are not under LGPL strictly speaking.
   # so an exception is valid here
   # ALSO: none of these are shipped to the customer. they're only used as dev dependencies.
-  - 'pkg:npm/%2540img/sharp-libvips-darwin-arm64@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-darwin-x64@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-linux-arm@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-linux-arm64@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-linux-ppc64@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-linux-riscv64@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-linux-s390x@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-linux-x64@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-linuxmusl-arm64@1.2.4'
-  - 'pkg:npm/%2540img/sharp-libvips-linuxmusl-x64@1.2.4'
-  - 'pkg:npm/%2540img/sharp-wasm32'
-  - 'pkg:npm/%2540img/sharp-win32-arm64'
-  - 'pkg:npm/%2540img/sharp-win32-ia32'
-  - 'pkg:npm/%2540img/sharp-win32-x64'
+  - 'pkg:npm/%40img/sharp-libvips-darwin-arm64'
+  - 'pkg:npm/%40img/sharp-libvips-darwin-x64'
+  - 'pkg:npm/%40img/sharp-libvips-linux-arm'
+  - 'pkg:npm/%40img/sharp-libvips-linux-arm64'
+  - 'pkg:npm/%40img/sharp-libvips-linux-ppc64'
+  - 'pkg:npm/%40img/sharp-libvips-linux-riscv64'
+  - 'pkg:npm/%40img/sharp-libvips-linux-s390x'
+  - 'pkg:npm/%40img/sharp-libvips-linux-x64'
+  - 'pkg:npm/%40img/sharp-libvips-linuxmusl-arm64'
+  - 'pkg:npm/%40img/sharp-libvips-linuxmusl-x64'
+  - 'pkg:npm/%40img/sharp-wasm32'
+  - 'pkg:npm/%40img/sharp-win32-arm64'
+  - 'pkg:npm/%40img/sharp-win32-ia32'
+  - 'pkg:npm/%40img/sharp-win32-x64'
   - 'pkg:npm/unicode-match-property-value-ecmascript@2.2.1'

.github/workflows/callable-canary-e2e-tests.yml

@@ -66,7 +66,8 @@ jobs:
           SEGMENT_DOWNLOAD_TIMEOUT_MINS: 2
 
       - name: Install
-        run: yarn
+        # Retry the install to guard against transient network failures (e.g. registry timeouts, DNS errors)
+        run: scripts/retry-yarn-script.sh -s install -n 3
         shell: bash
         working-directory: ./amplify-js
       - name: Build packages

AGENTS.md

@@ -0,0 +1,160 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in the **AWS Amplify JS** monorepo. Read this before making changes.
+
+## Repository Overview
+
+Amplify JS is a **Yarn + Turborepo** monorepo. Every package lives under `packages/<name>/`, each with its own `src/` and `package.json`. Packages are published under the `@aws-amplify/*` scope (plus the umbrella `aws-amplify` package).
+
+Key packages:
+
+| Package | Purpose |
+|---|---|
+| `@aws-amplify/core` | Shared runtime: config singleton, Hub, utils |
+| `@aws-amplify/auth` | Cognito authentication |
+| `@aws-amplify/storage` | S3 storage (client/utils + server/utils split) |
+| `@aws-amplify/api`, `api-graphql`, `api-rest` | API categories |
+| `@aws-amplify/analytics`, `geo`, `interactions`, `notifications`, `predictions`, `pubsub` | Feature categories |
+| `aws-amplify` | Umbrella package re-exporting category APIs |
+| `@aws-amplify/adapter-nextjs` | Next.js server adapter |
+
+## Environment
+
+| Requirement | Version |
+|---|---|
+| Node.js | 24 (pinned in CI; repo has no local `engines`/`.nvmrc`) |
+| Yarn | 1.22.x |
+
+## Build & Test Commands (MANDATORY: use `yarn`)
+
+**Always drive builds/tests/lint through `yarn`. NEVER invoke `tsc`, `eslint`, `jest`, `npx`, or `tsx` directly** — the workspace scripts wire up the correct config and dependency graph. Single-package targeting goes through Turbo's `--filter` (see below).
+
+```bash
+# Install
+yarn
+
+# Build
+yarn build                              # all packages
+yarn turbo run build --filter=@aws-amplify/auth   # single package (+ its deps)
+
+# Test
+yarn test                               # full suite (use before final confirmation)
+yarn turbo run test --filter=@aws-amplify/auth    # single package
+
+# Lint
+yarn lint                               # lint all packages
+yarn turbo run lint --filter=@aws-amplify/auth    # single package
+
+# Bundle size
+yarn test:size                          # size-limit check (only runs for packages that define it)
+yarn test:size --why                    # debug regression (Statoscope)
+
+# Watch mode for local dev
+yarn build:watch
+yarn link-all                           # make all packages linkable
+
+# Nuclear clean
+git clean -xdf
+```
+
+Run `yarn` from the **monorepo root or a package root**. During implementation you may narrow with file/suite/test filters, but always run the full `test` / `lint` / `build` for final confirmation.
+
+> **Single-package targeting must go through Turbo directly** — `yarn turbo run <task> --filter=@aws-amplify/<pkg>`. Do **not** pass `--filter` to the top-level `yarn build` / `yarn test` scripts: they are compound (`&&`) scripts, so the flag is misrouted to the trailing command and Turbo still runs unfiltered. (`--scope` is a Lerna flag — not valid for Turbo 2.x at all.)
+
+## Testing Conventions
+
+- **Do NOT mock `getConfig` on the Amplify singleton.** Mock the actual underlying modules/functions instead (real Amplify config approach).
+- Write or update unit tests for any added/modified code. Be especially vigilant with shared code (race conditions).
+- Passing unit tests are required for any PR that changes functionality.
+- **Bundle-size (`size-limit`) checks only apply to packages that configure them.** Eight packages declare a `size-limit` key (`aws-amplify`, `core`, `datastore`, `geo`, `interactions`, `predictions`, `pubsub`, `api-graphql`), but `yarn test:size` only exercises the seven that also define a `test:size` script (all of the above except `api-graphql`). Filtering it to a package without size-limit configured (e.g. `auth`, `storage`) is a no-op.
+
+## Code Conventions
+
+- **License headers are required** on source files (enforced by the `license-test` CI check).
+- **Never commit `tsconfig.tsbuildinfo` files.** A stray `packages/*/tsconfig.tsbuildinfo` causes `license-test` failures (`License not found in ...`). Remove it if generated.
+- Preserve existing comments, JSDoc, and logging statements.
+- Follow existing formatting (Prettier + ESLint config are applied via `yarn` scripts).
+
+## Git Hooks (Husky)
+
+The repo installs Husky hooks that run automatically — an agent committing or pushing will trigger them:
+
+- **`pre-commit`** — runs `lint-staged` (`eslint --fix` on staged `*.ts`/`*.tsx`). Do not bypass with `--no-verify`.
+- **`pre-push`** — runs a **git-secrets** scan and **blocks the push if git-secrets is not installed**. Install and register it before pushing:
+
+```bash
+brew install git-secrets   # or: apt-get install git-secrets
+git secrets --register-aws
+```
+
+## Changesets (required for functional changes)
+
+```bash
+yarn changeset
+```
+
+Creates a file in `.changeset/`:
+
+```markdown
+---
+'@aws-amplify/<package>': patch|minor|major
+---
+
+<type>(<scope>): description of the change.
+```
+
+**Skip a changeset** only for docs-only, formatting, or CI-only changes.
+
+## Branch Naming
+
+```
+<scope>/<type>/<description>
+```
+
+- **scope**: category or alias (e.g. `auth`, `storage`, `core`)
+- **type**: `feat` | `fix` | `docs` | `refactor` | `perf` | `test` | `build` | `ci` | `chore` | `revert`
+
+Examples: `auth/fix/refresh-token-race-condition`, `storage/feat/presigned-urls`
+
+## Commit / PR Flow
+
+1. Make changes in `packages/<category>/`.
+2. Add/update unit tests.
+3. Add a changeset (if functional).
+4. Validate: `yarn build` + `yarn test` (+ `yarn test:size` if bundle-sensitive).
+5. Commit with a conventional message: `<type>(<scope>): summary`.
+6. Push and open a PR filling out the template (description, linked issue, validation steps, checklist).
+
+## CI Checks (must pass before merge)
+
+| Check | Validates |
+|---|---|
+| `unit-tests` | Jest suites across packages |
+| `native-unit-tests` | React Native tests |
+| `bundle-size-tests` | Tree-shaken footprint (size-limit) |
+| `license-test` | License headers present |
+| `tsc-compliance-test` | TypeScript compilation |
+| `dependency-review` | No problematic dependencies |
+| `git-secrets-check` | No leaked AWS credentials |
+| `github-actions-test` | CI config validity |
+
+The `ci - Unit and Bundle tests have passed` gate turns green only when all above pass.
+
+## Maintenance Branch: `v5-stable`
+
+The `v5-stable` branch hosts Amplify JS v5 maintenance releases (security patches, critical fixes). **Do not apply this document's conventions there** — it uses different tooling (Lerna instead of Turborepo, no changesets, different setup and CI checks).
+
+When backporting a fix to v5: branch off `v5-stable`, target the PR at `v5-stable`, and follow the `AGENTS.md` **on that branch** for its specific conventions.
+
+## Do / Don't Summary
+
+**Do**
+- Use `yarn` for everything
+- Add tests + changesets
+- Keep license headers
+- Mock underlying modules, not `Amplify.getConfig`
+
+**Don't**
+- Run `tsc`/`jest`/`eslint`/`npx` directly
+- Commit `tsconfig.tsbuildinfo`
+- Strip existing comments or logging

CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This project's AI agent guidance lives in [AGENTS.md](./AGENTS.md).
+
+Please read **[AGENTS.md](./AGENTS.md)** for repository structure, build/test commands, code conventions, changeset requirements, and CI checks.

package.json

@@ -141,7 +141,8 @@
 		"serialize-javascript": "^7.0.5",
 		"@tootallnate/once": "3.0.1",
 		"uuid": "^11.1.1",
-		"joi": "^18.2.1"
+		"joi": "^18.2.1",
+		"**/next/sharp": "^0.35.0"
 	},
 	"packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }