@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/cap/deployment.md

@@ -0,0 +1,343 @@
+# CAP Deployment — Cloud Foundry, mta.yaml, XSUAA, HDI
+
+## mta.yaml — Complete Example
+
+```yaml
+_schema-version: '3.1'
+ID: bookshop
+description: CAP Bookshop Application
+version: 1.0.0
+modules:
+
+  # CAP Server (Node.js)
+  - name: bookshop-srv
+    type: nodejs
+    path: gen/srv
+    parameters:
+      buildpack: nodejs_buildpack
+      memory: 256M
+      disk-quota: 512M
+    build-parameters:
+      builder: npm
+    provides:
+      - name: srv-api
+        properties:
+          srv-url: ${default-url}
+    requires:
+      - name: bookshop-db
+      - name: bookshop-auth
+
+  # HANA DB Deployer
+  - name: bookshop-db-deployer
+    type: hdb
+    path: gen/db
+    parameters:
+      buildpack: nodejs_buildpack
+    requires:
+      - name: bookshop-db
+
+  # App Router (UI)
+  - name: bookshop-app
+    type: approuter.nodejs
+    path: app/router
+    parameters:
+      keep-existing-routes: true
+      disk-quota: 256M
+      memory: 256M
+    requires:
+      - name: srv-api
+        group: destinations
+        properties:
+          name: srv-api
+          url: ~{srv-url}
+          forwardAuthToken: true
+      - name: bookshop-auth
+    build-parameters:
+      requires:
+        - name: bookshop-ui
+          artifacts:
+            - ./*
+          target-path: resources
+
+  # UI Build
+  - name: bookshop-ui
+    type: html5
+    path: app/browse
+    build-parameters:
+      build-result: dist
+      builder: custom
+      commands:
+        - npm install
+        - npm run build
+
+resources:
+
+  # HDI Container (HANA)
+  - name: bookshop-db
+    type: com.sap.xs.hdi-container
+    parameters:
+      service: hana
+      service-plan: hdi-shared
+
+  # XSUAA (Authentication)
+  - name: bookshop-auth
+    type: org.cloudfoundry.managed-service
+    parameters:
+      service: xsuaa
+      service-plan: application
+      path: ./xs-security.json
+```
+
+## xs-security.json — Authentication Config
+
+```json
+{
+  "xsappname": "bookshop",
+  "tenant-mode": "dedicated",
+  "scopes": [
+    {
+      "name": "$XSAPPNAME.admin",
+      "description": "Admin access"
+    },
+    {
+      "name": "$XSAPPNAME.viewer",
+      "description": "Read-only access"
+    }
+  ],
+  "attributes": [
+    {
+      "name": "Country",
+      "description": "Country for data access",
+      "valueType": "string"
+    }
+  ],
+  "role-templates": [
+    {
+      "name": "Admin",
+      "description": "Administrator",
+      "scope-references": ["$XSAPPNAME.admin"],
+      "attribute-references": ["Country"]
+    },
+    {
+      "name": "Viewer",
+      "description": "Read-only user",
+      "scope-references": ["$XSAPPNAME.viewer"]
+    }
+  ],
+  "role-collections": [
+    {
+      "name": "BookshopAdmin",
+      "description": "Bookshop Administrators",
+      "role-template-references": ["$XSAPPNAME.Admin"]
+    },
+    {
+      "name": "BookshopViewer",
+      "description": "Bookshop Viewers",
+      "role-template-references": ["$XSAPPNAME.Viewer"]
+    }
+  ]
+}
+```
+
+## xs-app.json — App Router
+
+```json
+{
+  "welcomeFile": "/index.html",
+  "authenticationMethod": "route",
+  "routes": [
+    {
+      "source": "^/browse/(.*)$",
+      "target": "/browse/$1",
+      "destination": "srv-api",
+      "authenticationType": "xsuaa",
+      "csrfProtection": true
+    },
+    {
+      "source": "^/admin/(.*)$",
+      "target": "/admin/$1",
+      "destination": "srv-api",
+      "authenticationType": "xsuaa",
+      "csrfProtection": true
+    },
+    {
+      "source": "^(.*)$",
+      "target": "$1",
+      "service": "html5-apps-repo-rt",
+      "authenticationType": "xsuaa"
+    }
+  ]
+}
+```
+
+## CDS Service — Access Control
+
+```cds
+// Link CDS @requires to xs-security.json scopes
+service AdminService @(requires: 'admin') {
+  entity Books as projection on my.Books;
+}
+
+service CatalogService @(requires: 'authenticated-user') {
+  @readonly
+  entity Books as projection on my.Books;
+}
+
+// Entity-level restrictions
+service OrderService {
+  @requires: 'admin'
+  entity Orders as projection on my.Orders;
+
+  @requires: ['admin', 'support']
+  action cancelOrder(orderID: UUID);
+}
+
+// Instance-level (attribute-based)
+annotate OrderService.Orders with @(restrict: [
+  { grant: 'READ', to: 'viewer' },
+  { grant: ['CREATE', 'UPDATE', 'DELETE'], to: 'admin' },
+  { grant: 'READ', where: 'country = $user.Country' }
+]);
+```
+
+## Build & Deploy Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build for production (generates gen/ folder)
+cds build --production
+
+# Build MTA archive
+mbt build
+
+# Deploy to Cloud Foundry
+cf login -a https://api.cf.eu10.hana.ondemand.com
+cf deploy mta_archives/bookshop_1.0.0.mtar
+
+# Check deployment
+cf apps
+cf services
+
+# View logs
+cf logs bookshop-srv --recent
+
+# Undeploy (removes all modules + services)
+cf undeploy bookshop --delete-services
+```
+
+## HANA Configuration
+
+```json
+// package.json — database config
+{
+  "cds": {
+    "requires": {
+      "db": {
+        "kind": "hana",
+        "[development]": {
+          "kind": "sqlite",
+          "credentials": { "database": ":memory:" }
+        },
+        "[production]": {
+          "kind": "hana"
+        }
+      }
+    },
+    "hana": {
+      "deploy-format": "hdbtable"
+    }
+  }
+}
+```
+
+## Hybrid Development (Local + HANA)
+
+```bash
+# Bind to remote HANA service
+cf create-service-key bookshop-db bookshop-db-key
+cds bind --to bookshop-db:bookshop-db-key
+
+# Run locally with remote HANA
+cds watch --profile hybrid
+```
+
+## .cdsrc.json — Project Config
+
+```json
+{
+  "build": {
+    "target": "gen",
+    "tasks": [
+      { "for": "hana", "src": "db", "options": { "model": ["db", "srv"] } },
+      { "for": "node-cf", "src": "srv", "options": { "model": ["db", "srv"] } }
+    ]
+  },
+  "odata": {
+    "version": "v4"
+  }
+}
+```
+
+## Project Structure (Production)
+
+```
+project/
+├── app/
+│   ├── browse/             # UI module (Fiori)
+│   │   ├── webapp/
+│   │   └── package.json
+│   ├── router/             # App Router
+│   │   ├── xs-app.json
+│   │   └── package.json
+│   └── common.cds          # Shared annotations
+├── db/
+│   ├── schema.cds          # Data model
+│   ├── data/               # CSV seed data
+│   │   └── my.bookshop-Books.csv
+│   └── undeploy.json
+├── srv/
+│   ├── catalog-service.cds
+│   ├── catalog-service.js
+│   ├── admin-service.cds
+│   └── admin-service.js
+├── mta.yaml
+├── xs-security.json
+├── package.json
+└── .cdsrc.json
+```
+
+## CSV Seed Data
+
+```
+# db/data/my.bookshop-Books.csv
+ID;title;author_ID;stock;price;currency_code
+1;Wuthering Heights;101;12;11.11;EUR
+2;Jane Eyre;107;11;12.34;EUR
+3;The Raven;150;333;13.13;USD
+```
+
+File naming: `<namespace>-<Entity>.csv` with semicolon separator.
+
+## Rules
+- `cds build --production` before `mbt build` (generates gen/ folder)
+- xs-security.json `xsappname` must match MTA ID
+- `$XSAPPNAME` prefix auto-resolves to the app name at deploy time
+- HDI container: `hdi-shared` plan for shared HANA, `hdi-dynamic` for multi-tenant
+- App Router routes: order matters — first match wins
+- `@requires: 'authenticated-user'` for any logged-in user (no specific role)
+- CSV seed data: deployed with `hdb` deployer, semicolon separated
+- `[development]` / `[production]` profiles in package.json for env-specific config
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| Deploying without `cds build --production` | Build generates optimized gen/ folder |
+| Missing xs-security.json in mta.yaml | `path: ./xs-security.json` in auth resource |
+| Hardcoded credentials in code | Use XSUAA + destination service |
+| `tenant-mode: shared` for single-tenant | Use `dedicated` unless multi-tenant SaaS |
+| Missing CSRF protection on routes | `csrfProtection: true` in xs-app.json |
+| App Router without `forwardAuthToken` | Required for auth propagation to srv |
+| Deploying test data to production | Use `[development]` profile for seed data |
+| `cf push` instead of `cf deploy` | Use MTA deployment for multi-module apps |

package/dist/knowledge/cap/event-handlers.md

@@ -0,0 +1,287 @@
+# Event Handlers — CAP Node.js Service Implementation
+
+## Handler Registration (Class-Based)
+
+```js
+const cds = require('@sap/cds');
+
+module.exports = class CatalogService extends cds.ApplicationService {
+  async init() {
+    const { Books, Authors } = this.entities;
+
+    this.before('CREATE', Books, this.validateBook);
+    this.on('READ', Books, this.onReadBooks);
+    this.after('READ', Books, this.enrichBooks);
+    this.on('submitOrder', this.onSubmitOrder);
+
+    return super.init();
+  }
+
+  validateBook(req) { /* ... */ }
+  async onReadBooks(req) { /* ... */ }
+  enrichBooks(books, req) { /* ... */ }
+  async onSubmitOrder(req) { /* ... */ }
+}
+```
+
+## Handler Registration (Functional)
+
+```js
+module.exports = function() {
+  const { Books } = this.entities;
+
+  this.before('CREATE', Books, validateBook);
+  this.on('READ', Books, onReadBooks);
+  this.after('READ', Books, enrichBooks);
+
+  function validateBook(req) { /* ... */ }
+  async function onReadBooks(req) { /* ... */ }
+  function enrichBooks(books, req) { /* ... */ }
+}
+```
+
+## before Handlers — Validation and Enrichment
+
+```js
+// Validation (collect multiple errors)
+this.before('CREATE', 'Books', (req) => {
+  const { title, price } = req.data;
+  if (!title) req.error(400, 'Title is required', 'title');
+  if (price < 0) req.error(400, 'Price must be positive', 'price');
+});
+
+// Enrichment
+this.before('CREATE', 'Orders', (req) => {
+  req.data.status = 'draft';
+  req.data.createdAt = new Date();
+});
+
+// Authorization
+this.before('UPDATE', 'Books', async (req) => {
+  const book = await SELECT.one.from('Books', req.data.ID);
+  if (book.createdBy !== req.user.id && !req.user.is('admin')) {
+    req.reject(403, 'Not authorized');
+  }
+});
+```
+
+## on Handlers — Custom Implementation
+
+```js
+// Custom READ
+this.on('READ', 'Books', async (req) => {
+  return await cds.db.run(req.query);
+});
+
+// Delegate to default + post-process
+this.on('READ', 'Books', async (req, next) => {
+  const result = await next();
+  return result.filter(b => b.stock > 0);
+});
+
+// Action handler
+this.on('submitOrder', async (req) => {
+  const { book, quantity } = req.data;
+  const b = await SELECT.one.from('Books', book);
+  if (!b) return req.reject(404, 'Book not found');
+  if (b.stock < quantity) return req.reject(409, 'Insufficient stock');
+  await UPDATE('Books', book).set({ stock: { '-=': quantity } });
+  return { success: true };
+});
+
+// Bound action
+this.on('confirm', 'Orders', async (req) => {
+  const { ID } = req.params[0];
+  await UPDATE('Orders', ID).set({ status: 'confirmed' });
+});
+```
+
+## after Handlers — Post-Processing
+
+```js
+// Enrich results (first param is result data)
+this.after('READ', 'Books', (books, req) => {
+  for (const book of books) {
+    book.discount = book.stock > 100 ? '10%' : null;
+    book.available = book.stock > 0;
+  }
+});
+
+// Emit event after creation
+this.after('CREATE', 'Orders', async (order, req) => {
+  await this.emit('OrderCreated', { orderID: order.ID });
+});
+```
+
+## Request Object (req)
+
+```js
+this.on('CREATE', 'Books', (req) => {
+  req.event;      // 'CREATE', 'READ', 'UPDATE', 'DELETE', or action name
+  req.target;     // Entity definition (CSN)
+  req.entity;     // Entity name string
+  req.data;       // Request payload
+  req.params;     // URL parameters [{ID: '123'}]
+  req.query;      // CQN query object
+  req.user.id;             // User ID
+  req.user.is('admin');    // Role check
+  req.user.attr.country;   // User attribute
+  req.tenant;     // Tenant ID
+  req.locale;     // User locale
+  req.timestamp;  // Request timestamp
+});
+```
+
+## Error Handling
+
+```js
+// Immediate rejection (stops processing)
+req.reject(400, 'Bad request');
+req.reject(404, 'Not found');
+
+// Collect errors (continues, rejects at end of phase)
+req.error(400, 'Title required', 'title');
+req.error(400, 'Price required', 'price');
+
+// Warnings and info (returned in response headers, no rejection)
+req.warn(200, 'Stock is low');
+req.info(200, 'Price updated');
+
+// Standard CAP error classes
+const { errors } = require('@sap/cds');
+throw new errors.NotFound('Book not found');
+throw new errors.Unauthorized('Login required');
+throw new errors.Forbidden('Access denied');
+```
+
+## Wildcard Handlers
+
+```js
+this.before('*', 'Books', handler);     // All events on Books
+this.before('CREATE', '*', handler);    // CREATE on all entities
+this.before('*', handler);              // All events on all entities
+```
+
+## Draft Events
+
+```js
+this.on('NEW', 'Books', handler);      // Create draft
+this.on('EDIT', 'Books', handler);     // Edit existing as draft
+this.on('PATCH', 'Books', handler);    // Update draft fields
+this.on('SAVE', 'Books', handler);     // Activate/save draft
+this.on('CANCEL', 'Books', handler);   // Discard draft
+```
+
+## Database Operations in Handlers
+
+```js
+const { Books } = cds.entities;
+
+const books = await SELECT.from(Books).where({ stock: { '>': 0 } });
+const book = await SELECT.one.from(Books, bookId);
+await INSERT.into(Books).entries({ title: 'New', stock: 10 });
+await UPDATE(Books, bookId).set({ stock: 50 });
+await DELETE.from(Books, bookId);
+await UPSERT.into(Books).entries({ ID: bookId, title: 'Updated' });
+```
+
+## Transactions
+
+```js
+this.on('transferStock', async (req) => {
+  const { from, to, amount } = req.data;
+
+  // Handlers run inside automatic transaction
+  await UPDATE(Books, from).set({ stock: { '-=': amount } });
+  await UPDATE(Books, to).set({ stock: { '+=': amount } });
+
+  // Explicit transaction (when needed)
+  return cds.tx(async (tx) => {
+    await tx.run(UPDATE(Books, from).set({ stock: { '-=': amount } }));
+    await tx.run(UPDATE(Books, to).set({ stock: { '+=': amount } }));
+    return { success: true };
+  });
+});
+```
+
+## Service-to-Service Communication
+
+```js
+const adminSrv = await cds.connect.to('AdminService');
+const books = await adminSrv.read('Books');
+await adminSrv.send('updateStock', { book: bookId, delta: 10 });
+
+const externalApi = await cds.connect.to('ExternalAPI');
+const result = await externalApi.run(SELECT.from('Products'));
+```
+
+## Event Emission and Subscription
+
+```js
+// Emit
+this.emit('OrderCreated', { orderID: order.ID });
+
+// Subscribe
+const messaging = await cds.connect.to('messaging');
+messaging.on('OrderCreated', async (msg) => {
+  const { orderID } = msg.data;
+});
+```
+
+## Lifecycle Hooks
+
+```js
+req.before('commit', async () => { /* before transaction commit */ });
+req.on('succeeded', async () => { /* after successful commit (outside tx) */ });
+req.on('failed', async () => { /* after rollback */ });
+req.on('done', async () => { /* always — cleanup */ });
+```
+
+## Context Access
+
+```js
+// Available anywhere in async call chain
+const { user, tenant, locale } = cds.context;
+
+// Set context for background jobs
+cds.context = { user: new cds.User('system'), tenant: 't1' };
+```
+
+## TypeScript
+
+```ts
+import cds from '@sap/cds';
+import { Request } from '@sap/cds';
+
+export default class CatalogService extends cds.ApplicationService {
+  async init() {
+    this.on('READ', 'Books', this.readBooks);
+    return super.init();
+  }
+  private async readBooks(req: Request) {
+    return await cds.db.run(req.query);
+  }
+}
+```
+
+## Rules
+
+- `before` handlers: validation and enrichment; `on` handlers: replace default logic; `after` handlers: post-process results
+- `req.reject()` stops immediately; `req.error()` collects and rejects at end of phase
+- `after('READ')` callback signature is `(results, req)` — results first
+- Handlers run inside automatic transactions; explicit `cds.tx()` rarely needed
+- Always call `return super.init()` at end of class-based `init()`
+- Use `next()` in `on` handlers to delegate to the default/next handler in chain
+- Bound action params accessed via `req.params[0]` for the entity key, `req.data` for action params
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Pattern |
+|---|---|
+| Forgetting `return super.init()` in class-based handler | Always end `init()` with `return super.init()` |
+| Using `req.reject()` for multiple validation errors | Use `req.error()` to collect, framework rejects if errors exist |
+| `after('READ')` with `(req, books)` param order | Correct order: `(books, req)` |
+| Business logic in `before` that should be in `on` | `before` = validate/enrich; `on` = business logic |
+| Direct DB writes without considering CAP transactions | Use CQL APIs; handlers auto-manage transactions |
+| Forgetting `async` on handlers that use `await` | Always mark handlers as `async` when using `await` |
+| Not calling `next()` when extending default READ | Without `next()`, default query is skipped entirely |