Fix/dx 7557

.cursor/rules/README.md

@@ -0,0 +1,7 @@
+# Cursor (optional)
+
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
+
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
+
+Path to AGENTS.md: from this file use `../../AGENTS.md`.

.github/workflows/back-merge-pr.yml

@@ -0,0 +1,54 @@
+name: Back-merge master to development
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  open-back-merge-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Open back-merge PR if needed
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          BASE_BRANCH="development"
+          SOURCE_BRANCH="master"
+
+          git fetch origin "$BASE_BRANCH" "$SOURCE_BRANCH"
+
+          if ! git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH"; then
+            echo "Base branch '$BASE_BRANCH' does not exist on origin; skipping."
+            exit 0
+          fi
+
+          SOURCE_SHA=$(git rev-parse "origin/$SOURCE_BRANCH")
+          BASE_SHA=$(git rev-parse "origin/$BASE_BRANCH")
+
+          if [ "$SOURCE_SHA" = "$BASE_SHA" ]; then
+            echo "$SOURCE_BRANCH and $BASE_BRANCH are at the same commit; nothing to back-merge."
+            exit 0
+          fi
+
+          EXISTING=$(gh pr list --repo "${{ github.repository }}"             --base "$BASE_BRANCH"             --head "$SOURCE_BRANCH"             --state open             --json number             --jq 'length')
+
+          if [ "$EXISTING" -gt 0 ]; then
+            echo "An open PR from $SOURCE_BRANCH to $BASE_BRANCH already exists; skipping."
+            exit 0
+          fi
+
+          gh pr create --repo "${{ github.repository }}"             --base "$BASE_BRANCH"             --head "$SOURCE_BRANCH"             --title "chore: back-merge $SOURCE_BRANCH into $BASE_BRANCH"             --body "Automated back-merge after changes landed on \\`$SOURCE_BRANCH\\`. Review and merge to keep \\`$BASE_BRANCH\\` in sync."
+
+          echo "Created back-merge PR $SOURCE_BRANCH -> $BASE_BRANCH."

.github/workflows/check-version-bump.yml

@@ -0,0 +1,79 @@
+# Catches when developers forget to bump package.json for release-affecting changes.
+# App code changes (app.js, bin/, config/, routes/, views/, etc.) require a version bump vs latest tag.
+# Skips for: test-only, docs, .github (workflows/config), dependency-only bumps without app edits.
+name: Check Version Bump
+
+on:
+  pull_request:
+
+jobs:
+  version-bump:
+    name: Version bump
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed files and version bump
+        id: detect
+        run: |
+          if git rev-parse HEAD^2 >/dev/null 2>&1; then
+            FILES=$(git diff --name-only HEAD^1 HEAD^2)
+          else
+            FILES=$(git diff --name-only HEAD~1 HEAD)
+          fi
+          VERSION_FILES_CHANGED=false
+          echo "$FILES" | grep -qx 'package.json' && VERSION_FILES_CHANGED=true
+          echo "version_files_changed=$VERSION_FILES_CHANGED" >> $GITHUB_OUTPUT
+          # App source paths for this boilerplate (no lib/webpack/dist); .github/ and test/ do not count
+          CODE_CHANGED=false
+          echo "$FILES" | grep -qE '^app\.js$|^bin/|^config/|^middlewares/|^models/|^public/|^routes/|^views/|^schemaNentries/' && CODE_CHANGED=true
+          echo "$FILES" | grep -qx 'package.json' && CODE_CHANGED=true
+          echo "code_changed=$CODE_CHANGED" >> $GITHUB_OUTPUT
+
+      - name: Skip when only test/docs/.github changed
+        if: steps.detect.outputs.code_changed != 'true'
+        run: |
+          echo "No release-affecting files changed (e.g. only test/docs/.github). Skipping version-bump check."
+          exit 0
+
+      - name: Fail when version bump was missed
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed != 'true'
+        run: |
+          echo "::error::This PR has code changes but no version bump. Please bump the version in package.json."
+          exit 1
+
+      - name: Setup Node
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Check version bump
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
+        run: |
+          set -e
+          PKG_VERSION=$(node -p "require('./package.json').version.replace(/^v/, '')")
+          if [ -z "$PKG_VERSION" ]; then
+            echo "::error::Could not read version from package.json"
+            exit 1
+          fi
+          git fetch --tags --force 2>/dev/null || true
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No existing tags found. Skipping version-bump check (first release)."
+            exit 0
+          fi
+          LATEST_VERSION="${LATEST_TAG#v}"
+          LATEST_VERSION="${LATEST_VERSION%%-*}"
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then
+            echo "::error::Version bump required: package.json version ($PKG_VERSION) is not greater than latest tag ($LATEST_TAG). Please bump the version in package.json."
+            exit 1
+          fi
+          if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then
+            echo "::error::Version bump required: package.json version ($PKG_VERSION) equals latest tag ($LATEST_TAG). Please bump the version in package.json."
+            exit 1
+          fi
+          echo "Version bump check passed: package.json is at $PKG_VERSION (latest tag: $LATEST_TAG)."

AGENTS.md

@@ -0,0 +1,48 @@
+# Contentstack DataSync Content Store (AWS S3) – Agent guide
+
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
+
+## What this repo is
+
+| Field | Detail |
+| --- | --- |
+| **Name:** | `contentstack-content-store-aws-s3` ([package.json](package.json)); published usage in docs may reference `@contentstack/datasync-content-store-aws-s3`. Repository: see [package.json `repository`](package.json) for the canonical Git URL. |
+| **Purpose:** | TypeScript npm package that implements the Contentstack DataSync **content store** driver for **Amazon S3**: persists published entries, content types, and related payloads to a bucket when used with DataSync Manager and the webhook listener. |
+| **Out of scope (if any):** | Does not implement the HTTP webhook server (use `@contentstack/webhook-listener`), asset storage (separate asset-store package), or DataSync orchestration (`datasync-manager`)—this repo is only the S3 content-store implementation. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | TypeScript (see [tsconfig.json](tsconfig.json)); **Node.js** `>=22` ([package.json `engines`](package.json)). |
+| Build | `npm run build-ts` → `tsc`; output `dist/`, declarations `typings/`. |
+| Tests | Jest + ts-jest ([jest.config.js](jest.config.js)); tests under `src/__tests__/**/*.test.ts`. |
+| Lint / coverage | TSLint ([tslint.json](tslint.json)), `npm run tslint`; Jest coverage to `coverage/` (see [jest.config.js](jest.config.js)). |
+| Other | AWS SDK v2 (`aws-sdk`); lodash; debug; integrates with `@contentstack/webhook-listener` types at the DataSync boundary. |
+
+## Commands (quick reference)
+
+| Command type | Command |
+| --- | --- |
+| Build | `npm run build-ts` |
+| Test | `npm test` |
+| Lint | `npm run tslint` |
+
+**CI / automation:** GitHub Actions under [.github/workflows/](.github/workflows/) (e.g. SCA via Snyk [.github/workflows/sca-scan.yml](.github/workflows/sca-scan.yml), policy scan, CodeQL, Jira integration). There is no separate workflow file in this repo that only runs `npm test`; run tests locally before opening a PR.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Development workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, commands, Husky, CI touchpoints. |
+| Content Store (AWS S3) API | [skills/content-store-aws-s3-sdk/SKILL.md](skills/content-store-aws-s3-sdk/SKILL.md) | Public exports, config, DataSync boundaries, errors. |
+| TypeScript conventions | [skills/typescript/SKILL.md](skills/typescript/SKILL.md) | Layout, compiler expectations, style alignment with TSLint. |
+| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Jest layout, mocks, coverage, credentials. |
+| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist for this package. |
+| Framework & platform | [skills/framework/SKILL.md](skills/framework/SKILL.md) | AWS S3 usage, dependencies, packaging notes. |
+
+An index with “when to use” hints is in [skills/README.md](skills/README.md).
+
+## Using Cursor (optional)
+
+If you use **Cursor**, [.cursor/rules/README.md](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- Initial changelog file.