chore(api): add OpenAPI diff tooling, API_CHANGELOG and CI job

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+<!-- Please describe the change in this PR. -->
+
+- What changed? Describe the change and why it was made.
+
+- Is this a breaking API change? If yes, include details below and add the label `api-breaking-change`.
+
+If this PR introduces any breaking changes to the API, add a clear description under a `BREAKING CHANGE` heading and update docs/API_CHANGELOG.md (or run `npm run api:update-changelog` to auto-generate an entry). Example:
+
+```
+BREAKING CHANGE: Removed endpoint `POST /v1/old-route` — replaced by `POST /v1/new-route`.
+```

.github/workflows/ci.yml

@@ -118,3 +118,51 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run build
+
+  api-diff:
+    name: API Diff
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - name: Fetch main snapshot
+        run: |
+          git fetch origin main
+          mkdir -p docs/openapi
+          if git show origin/main:docs/openapi/latest.json > docs/openapi/previous.json 2>/dev/null; then
+            echo 'Fetched previous OpenAPI snapshot from main'
+          else
+            echo 'No previous OpenAPI snapshot found on main'
+            rm -f docs/openapi/previous.json
+          fi
+      - name: Generate current OpenAPI spec
+        run: npm run api:spec
+      - name: Run openapi-diff
+        run: |
+          if [ -f docs/openapi/previous.json ]; then
+            npx openapi-diff docs/openapi/previous.json docs/openapi/current.json > api-diff.txt || true
+          else
+            echo 'SKIP: no previous OpenAPI snapshot available' > api-diff.txt
+          fi
+      - name: Check for breaking changes
+        shell: bash
+        run: |
+          if grep -E 'Incompatible|Removed|ERROR|ERROR:' api-diff.txt; then
+            echo 'Detected potentially breaking API changes.' >&2
+            PR_BODY="${{ github.event.pull_request.body }}"
+            if echo "$PR_BODY" | grep -qiE 'api-breaking-change|BREAKING CHANGE'; then
+              echo 'Breaking change acknowledged in PR body'
+            else
+              echo 'Breaking API changes detected but not documented in PR.' >&2
+              cat api-diff.txt >&2
+              exit 1
+            fi
+          else
+            echo 'No breaking API changes detected.'
+          fi

dist/app.service.d.ts

@@ -1,3 +1,5 @@
 export declare class AppService {
+    private readonly apiVersion;
     getHello(): string;
+    getVersion(): string;
 }