chore(deps): upgrade to CAP 10.2

docs/superpowers/plans/2026-11-01-cap-10-2-upgrade.md

@@ -0,0 +1,310 @@
+# CAP 10.2 Upgrade Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Upgrade all CAP and CAP plugin packages from 10.1.x to 10.2.x, and opt into new 10.2 features where beneficial.
+
+**Architecture:** This is a dependency-bump upgrade. Core changes are: bump `@sap/cds` and `@sap/cds-dk` to `^10.2.0`, bump all `@cap-js/*` plugins to their latest 10.2-compatible versions, relax the `@cap-js/ai` tilde pin to `^1.3.0`, and evaluate three opt-in flags (`draft_admin_integrity`, `draft_orphan_cleanup`, and the new `@cds.autoexpose: false` for internal services). No schema changes are required; no Java dependencies in this project.
+
+**Tech Stack:** Node.js 22.23.4, `@sap/cds` ^10.2.x, CAP plugin ecosystem, SQLite (dev/test), HANA Cloud (hybrid/prod)
+
+**Spec:** https://cap.cloud.sap/docs/releases/2026/oct26
+
+## Global Constraints
+
+- Node.js 22.23.4 — pinned exactly in `engines.node`; do NOT change this
+- All CAP Node.js only — no Java migration steps apply
+- Tests must pass: `npm test` (in-memory SQLite, fast); hybrid tests are out-of-scope for this PR
+- Never write raw SQL — use `cds.ql` or CQL
+- PR targets `DEV` branch (never `main`)
+- `@cap-js/graphql` is currently pinned to `0.14.0` (exact, no caret); only bump if a new release is available
+- `@cap-js/attachments` is currently pinned to `4.0.0` (exact); only bump if a new release is available
+- `@cap-js/data-inspector` is currently pinned to `1.0.5` (exact); only bump if `2.0.1` is confirmed for this ecosystem
+- The `mcp.per_action_tool: true` config remains in place — the "single `call` tool" 10.2 default does not apply here since we intentionally override it
+
+## Review Focus
+
+- `@cap-js/ai` version jump from `~1.1.0` to `^1.3.0` spans two minor versions: verify AI-author (ValueList recommendations), ONNX model initialization, and `AICore-mocked` local mode still work after bump
+- `cds.fiori.draft_admin_integrity: true` changes which delete handlers are called on draft entities — verify that `AdminService` draft entities (`Tutorials`, `Missions`, `Groups`, etc.) still delete cleanly and that any custom `@before DELETE` handlers are not skipped
+- `draft_orphan_cleanup` is a new background job; verify it does not interfere with the CAP scheduler / `CronService` under `cds watch` or unit tests
+- `@cap-js/change-tracking` bumped to 2.2.3 — verify that change tracking on `TutorialMeta` and related entities still works and that tracked payloads in tests match expected structure
+- `@sap/cds` 10.2.x removes `@odata.metadataEtag` from default responses; the `./test/` suite may assert on response shapes — scan for any assertion on `@odata.metadataEtag` and update or remove
+
+---
+
+## Task 1: Bump core CAP packages and run baseline tests
+
+**Files:**
+- Modify: `package.json` (dependency version strings only)
+- Verify: `package-lock.json` (auto-generated by npm install)
+
+**Interfaces:**
+- Produces: updated `package.json` and `package-lock.json` that later tasks depend on
+
+- [ ] **Step 1: Create a new branch off DEV**
+
+```bash
+git fetch origin
+git checkout -b upgrade/cap-10.2 origin/DEV
+```
+
+- [ ] **Step 2: Bump `@sap/cds` and `@sap/cds-dk` in `package.json`**
+
+Change:
+```json
+"@sap/cds": "^10.1.0"
+"@sap/cds-dk": "^10.1.1"
+```
+To:
+```json
+"@sap/cds": "^10.2.0"
+"@sap/cds-dk": "^10.2.0"
+```
+
+- [ ] **Step 3: Run `npm install` and verify resolution**
+
+```bash
+npm install 2>&1 | tail -20
+node -e "console.log(require('@sap/cds/package.json').version)"
+```
+Expected: version printed starts with `10.2.`
+
+- [ ] **Step 4: Run baseline unit tests**
+
+```bash
+npm test 2>&1 | tail -40
+```
+Expected: all tests pass (or same failures as before this task)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add package.json package-lock.json
+git commit -m "chore(deps): bump @sap/cds and cds-dk to ^10.2.0"
+```
+
+---
+
+## Task 2: Bump CAP plugin packages
+
+**Files:**
+- Modify: `package.json`
+- Verify: `package-lock.json`
+
+**Interfaces:**
+- Consumes: branch from Task 1 with `@sap/cds` 10.2 installed
+- Produces: all `@cap-js/*` plugins and `@cap-js-community/websocket` bumped to their current latest
+
+**Version targets** (verified available on npm before writing this plan):
+
+| Package | Current | Target |
+|---|---|---|
+| `@cap-js/ai` | `~1.1.0` | `^1.3.0` |
+| `@cap-js/audit-logging` | `^1.3.0` | `^1.3.0` (already at latest; keep) |
+| `@cap-js/change-tracking` | `^2.2.2` | `^2.2.3` |
+| `@cap-js/hana` | `^3.1.0` | `^3.1.2` |
+| `@cap-js/mcp` | `1.3.0` (exact) | `^1.5.0` |
+| `@cap-js/ord` | `^1.9.3` | `^1.10.2` |
+| `@cap-js/sqlite` | `^3.1.0` | `^3.1.2` |
+| `@cap-js/telemetry` | `^2.0.1` | `^2.2.0` |
+| `@cap-js-community/websocket` | `^1.11.1` | `^1.11.4` |
+| `@cap-js/cds-test` (devDep) | `^1.0.2` | `^1.0.2` (keep; latest is same) |
+| `@cap-js/data-inspector` | `1.0.5` (exact) | bump to `2.0.1` (exact) only if no breaking API changes confirmed |
+| `@cap-js/graphql` | `0.14.0` (exact) | keep at `0.14.0` (no new release) |
+| `@cap-js/attachments` | `4.0.0` (exact) | keep at `4.0.0` (no new release) |
+
+- [ ] **Step 1: Apply version bumps to `package.json`**
+
+Edit the `dependencies` and `devDependencies` blocks per the table above. For `@cap-js/data-inspector`, check `npm info @cap-js/data-inspector versions --json` first — if the `2.0.1` release notes indicate any breaking API changes for this project's usage (search for `data-inspector` in `srv/`), keep it at `1.0.5`.
+
+- [ ] **Step 2: Run `npm install`**
+
+```bash
+npm install 2>&1 | tail -20
+```
+Expected: no peer dependency errors
+
+- [ ] **Step 3: Run unit tests**
+
+```bash
+npm test 2>&1 | tail -40
+```
+Expected: all tests pass
+
+- [ ] **Step 4: Verify AI plugin still initializes**
+
+```bash
+node -e "const cds = require('@sap/cds'); const ai = require('@cap-js/ai'); console.log('AI plugin loaded:', ai.version || 'ok')" 2>&1
+```
+Expected: no error
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add package.json package-lock.json
+git commit -m "chore(deps): bump @cap-js/* plugins to latest 10.2-compatible versions"
+```
+
+---
+
+## Task 3: Evaluate and adopt opt-in 10.2 flags
+
+**Files:**
+- Modify: `package.json` (`.cds` block → `fiori` section)
+
+**Interfaces:**
+- Consumes: Task 2 (all plugins at 10.2 versions)
+- Produces: `package.json` CDS config updated with evaluated opt-in flags
+
+The three 10.2 opt-ins to evaluate:
+
+1. **`cds.fiori.draft_admin_integrity: true`** — draft deletion uses DB cascades; only matters if draft entities have custom delete handlers. Search before adopting.
+2. **`cds.fiori.draft_orphan_cleanup: true`** — background cleanup of orphaned draft rows; safe to adopt.
+3. **`@cds.autoexpose: false`** annotation — prevents entity duplication in exported APIs; applies to CDS model files, not `package.json`.
+
+- [ ] **Step 1: Check for custom draft delete handlers**
+
+```bash
+grep -rn "DELETE\|draft.*delete\|delete.*draft" srv/ --include="*.js" | grep -i "before\|on\|after" | head -20
+```
+
+If any handler targets draft entities with custom logic, skip `draft_admin_integrity` for now and note it in the commit message.
+
+- [ ] **Step 2: Adopt `draft_orphan_cleanup`**
+
+In the `cds.fiori` section of `package.json` (create it if absent):
+
+```json
+"fiori": {
+  "draft_orphan_cleanup": true
+}
+```
+
+- [ ] **Step 3: Conditionally adopt `draft_admin_integrity`**
+
+If Step 1 found no custom draft delete handlers, add to `cds.fiori`:
+
+```json
+"draft_admin_integrity": true
+```
+
+If custom handlers found, skip and add a comment in the PR description explaining why.
+
+- [ ] **Step 4: Run unit tests to verify draft behavior unchanged**
+
+```bash
+npm test -- --grep "draft" 2>&1 | tail -30
+```
+Expected: tests related to drafts pass; if `draft_admin_integrity` causes failures, revert only that flag.
+
+- [ ] **Step 5: Run the full test suite**
+
+```bash
+npm test 2>&1 | tail -40
+```
+Expected: all tests pass
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add package.json
+git commit -m "feat(cap): adopt CAP 10.2 draft opt-in flags (orphan_cleanup[, admin_integrity])"
+```
+
+---
+
+## Task 4: Check for metadataEtag and CqnSelect.getTransformations impacts
+
+**Files:**
+- Modify: any test files in `test/` that assert on `@odata.metadataEtag` (only if found)
+- Modify: any service code that calls `CqnSelect.getTransformations()` and mutates the result (only if found)
+
+**Interfaces:**
+- Consumes: Task 2 (cds 10.2 installed)
+- Produces: tests and code that are compatible with 10.2 breaking changes
+
+- [ ] **Step 1: Scan test files for `metadataEtag` assertions**
+
+```bash
+grep -rn "metadataEtag" test/ --include="*.js" --include="*.ts" 2>&1
+```
+
+If found: remove or update assertions — the property is no longer in default OData responses; it only appears when `Accept: application/json;odata.metadata=full` is set.
+
+- [ ] **Step 2: Scan service code for `getTransformations()` mutation patterns**
+
+```bash
+grep -rn "getTransformations" srv/ --include="*.js" 2>&1
+```
+
+If found and the result is mutated (e.g., `.push()`, `.splice()`): update to use `Select.transformations(List)` instead.
+
+- [ ] **Step 3: Run full test suite**
+
+```bash
+npm test 2>&1 | tail -40
+```
+Expected: all tests pass
+
+- [ ] **Step 4: Commit (only if changes were made)**
+
+```bash
+git add test/ srv/
+git commit -m "fix(cap10.2): remove metadataEtag assertions, use Select.transformations() for mutations"
+```
+
+If no changes were needed, skip this commit and note "no code changes required for breaking changes" in the PR.
+
+---
+
+## Task 5: Update CLAUDE.md and open PR
+
+**Files:**
+- Modify: `CLAUDE.md` (version references)
+- No `docs/` changes needed — this is a version bump, not a new feature
+
+**Interfaces:**
+- Consumes: all prior tasks complete, tests green
+
+- [ ] **Step 1: Update version references in CLAUDE.md**
+
+Search for `10.1` in `CLAUDE.md` and update to `10.2` where they refer to the CAP version being used:
+
+```bash
+grep -n "10\.1\|cds 10" CLAUDE.md | head -20
+```
+
+Only update references to the current CAP version; do not update unrelated version numbers.
+
+- [ ] **Step 2: Run full test suite one final time**
+
+```bash
+npm test 2>&1 | tail -40
+```
+Expected: all tests pass
+
+- [ ] **Step 3: Open PR targeting DEV**
+
+```bash
+gh pr create \
+  --base DEV \
+  --title "chore(deps): upgrade to CAP 10.2" \
+  --body "$(cat <<'EOF'
+## Summary
+- Bumps `@sap/cds` and `@sap/cds-dk` to `^10.2.0`
+- Updates all `@cap-js/*` plugins to latest 10.2-compatible versions
+- Relaxes `@cap-js/ai` pin from `~1.1.0` to `^1.3.0`
+- Adopts CAP 10.2 opt-in flags: `draft_orphan_cleanup` (and `draft_admin_integrity` if no custom handlers found)
+- No schema changes; no Java migration steps
+
+## Breaking changes addressed
+- `@odata.metadataEtag` removed from default OData responses — scanned and updated if needed
+- `CqnSelect.getTransformations()` immutable — scanned and updated if needed
+
+## Test plan
+- [ ] `npm test` passes (in-memory SQLite)
+- [ ] Dev server starts: `cds watch` (manual check)
+- [ ] AI plugin initializes without error on `cds watch` startup
+EOF
+)"
+```