@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/abap-cds/metadata-extensions.md

@@ -0,0 +1,294 @@
+# CDS Metadata Extensions — DDLX for UI annotations
+
+## Purpose
+
+Separate UI annotations from CDS data model. Requires `@Metadata.allowExtensions: true` on the CDS view.
+
+## Basic Metadata Extension
+
+```abap
+@Metadata.layer: #CORE
+annotate entity ZC_Travel with
+{
+  @UI.facet: [
+    { id: 'Travel',  type: #IDENTIFICATION_REFERENCE, label: 'Travel',   position: 10 },
+    { id: 'Booking', type: #LINEITEM_REFERENCE,       label: 'Bookings', position: 20,
+      targetElement: '_Booking' }
+  ]
+
+  @UI.hidden: true
+  TravelID;
+
+  @UI: {
+    lineItem:       [{ position: 10 }],
+    selectionField: [{ position: 10 }],
+    identification: [{ position: 10 }]
+  }
+  AgencyID;
+
+  @UI: {
+    lineItem:       [{ position: 20 }],
+    selectionField: [{ position: 20 }],
+    identification: [{ position: 20 }]
+  }
+  CustomerID;
+
+  @UI: {
+    lineItem:       [{ position: 30 }],
+    identification: [{ position: 30 }]
+  }
+  BeginDate;
+
+  @UI.identification: [{ position: 40 }]
+  BookingFee;
+
+  @UI: {
+    lineItem:       [{ position: 40 }],
+    identification: [{ position: 50 }]
+  }
+  TotalPrice;
+
+  @UI: {
+    lineItem:       [{ position: 50 }],
+    selectionField: [{ position: 30 }],
+    identification: [{ position: 60 }],
+    textArrangement: #TEXT_ONLY
+  }
+  OverallStatus;
+}
+```
+
+## @Metadata.layer
+
+| Layer | Priority | Use |
+|-------|:--------:|-----|
+| `#CORE` | Lowest | Base annotations (application developer) |
+| `#LOCALIZATION` | Low | Language-specific overrides |
+| `#INDUSTRY` | Medium | Industry solution overrides |
+| `#PARTNER` | High | Partner customizations |
+| `#CUSTOMER` | Highest | Customer overrides (wins over all) |
+
+Higher layer annotations override lower layer for the same field + annotation.
+
+## UI Facets — Object Page Sections
+
+```abap
+@UI.facet: [
+  " Simple identification section
+  { id: 'General',
+    type: #IDENTIFICATION_REFERENCE,
+    label: 'General Information',
+    position: 10 },
+
+  " Child entity table
+  { id: 'Items',
+    type: #LINEITEM_REFERENCE,
+    label: 'Order Items',
+    position: 20,
+    targetElement: '_Item' },
+
+  " Field group section
+  { id: 'Pricing',
+    type: #FIELDGROUP_REFERENCE,
+    label: 'Pricing',
+    position: 30,
+    targetQualifier: 'PricingGroup' },
+
+  " Collection (groups sub-facets)
+  { id: 'Admin',
+    type: #COLLECTION,
+    label: 'Administration',
+    position: 40 },
+  { id: 'AdminDates',
+    type: #FIELDGROUP_REFERENCE,
+    label: 'Dates',
+    position: 10,
+    parentId: 'Admin',
+    targetQualifier: 'DatesGroup' },
+  { id: 'AdminUsers',
+    type: #FIELDGROUP_REFERENCE,
+    label: 'Users',
+    position: 20,
+    parentId: 'Admin',
+    targetQualifier: 'UsersGroup' }
+]
+```
+
+## Facet Types
+
+| Type | Target | Use |
+|------|--------|-----|
+| `#IDENTIFICATION_REFERENCE` | Fields with `@UI.identification` | Main details form |
+| `#LINEITEM_REFERENCE` | Child entity `targetElement` | Child table |
+| `#FIELDGROUP_REFERENCE` | Fields with `@UI.fieldGroup` matching `targetQualifier` | Grouped form |
+| `#COLLECTION` | Sub-facets via `parentId` | Tab/section container |
+| `#DATAPOINT_REFERENCE` | `@UI.dataPoint` matching qualifier | KPI in header |
+| `#STATUS_INFO_REFERENCE` | Status field | Status in header |
+
+## UI Header Info
+
+```abap
+@UI.headerInfo: {
+  typeName: 'Travel',
+  typeNamePlural: 'Travels',
+  title: { type: #STANDARD, value: 'Description' },
+  description: { type: #STANDARD, value: 'TravelID' },
+  imageUrl: 'ImageURL'
+}
+```
+
+## Actions in Metadata Extension
+
+```abap
+@Metadata.layer: #CORE
+annotate entity ZC_Travel with
+{
+  " Action buttons in list table
+  @UI.lineItem: [
+    { position: 10 },
+    { type: #FOR_ACTION, dataAction: 'acceptTravel', label: 'Accept' },
+    { type: #FOR_ACTION, dataAction: 'rejectTravel', label: 'Reject' }
+  ]
+  TravelID;
+
+  " Action buttons on object page
+  @UI.identification: [
+    { position: 10 },
+    { type: #FOR_ACTION, dataAction: 'acceptTravel', label: 'Accept', position: 1 },
+    { type: #FOR_ACTION, dataAction: 'rejectTravel', label: 'Reject', position: 2 }
+  ]
+  TravelID;
+}
+```
+
+## Field Group
+
+```abap
+@Metadata.layer: #CORE
+annotate entity ZC_Order with
+{
+  @UI.fieldGroup: [{ qualifier: 'PricingGroup', position: 10 }]
+  NetAmount;
+
+  @UI.fieldGroup: [{ qualifier: 'PricingGroup', position: 20 }]
+  TaxAmount;
+
+  @UI.fieldGroup: [{ qualifier: 'PricingGroup', position: 30 }]
+  TotalAmount;
+
+  @UI.fieldGroup: [{ qualifier: 'DatesGroup', position: 10 }]
+  CreatedAt;
+
+  @UI.fieldGroup: [{ qualifier: 'DatesGroup', position: 20 }]
+  LastChangedAt;
+}
+```
+
+## DataPoint (Header KPIs)
+
+```abap
+@UI.dataPoint: {
+  qualifier: 'StatusDP',
+  title: 'Status',
+  criticality: 'StatusCriticality'
+}
+OverallStatus;
+
+@UI.dataPoint: {
+  qualifier: 'PriceDP',
+  title: 'Total Price'
+}
+TotalPrice;
+
+" Reference in header facets
+@UI.facet: [
+  { id: 'HeaderStatus',
+    type: #DATAPOINT_REFERENCE,
+    purpose: #HEADER,
+    targetQualifier: 'StatusDP',
+    position: 10 },
+  { id: 'HeaderPrice',
+    type: #DATAPOINT_REFERENCE,
+    purpose: #HEADER,
+    targetQualifier: 'PriceDP',
+    position: 20 }
+]
+```
+
+## Criticality
+
+```abap
+" Computed field in CDS (or virtual field set in handler)
+case overall_status
+  when 'O' then 2   " Open = yellow (Critical)
+  when 'A' then 3   " Accepted = green (Positive)
+  when 'X' then 1   " Rejected = red (Negative)
+  else 0             " grey (Neutral)
+end as StatusCriticality,
+
+" Referenced in annotation
+@UI.lineItem: [{ position: 50, criticality: 'StatusCriticality' }]
+OverallStatus;
+```
+
+| Value | Color | Meaning |
+|:-----:|-------|---------|
+| 0 | Grey | Neutral |
+| 1 | Red | Negative/Error |
+| 2 | Yellow | Critical/Warning |
+| 3 | Green | Positive/Success |
+| 5 | Blue | Information |
+
+## Complete Child Metadata Extension
+
+```abap
+@Metadata.layer: #CORE
+annotate entity ZC_Booking with
+{
+  @UI.facet: [
+    { id: 'Booking', type: #IDENTIFICATION_REFERENCE, label: 'Booking Details', position: 10 }
+  ]
+
+  @UI.hidden: true
+  TravelID;
+
+  @UI.hidden: true
+  BookingID;
+
+  @UI: { lineItem: [{ position: 10 }], identification: [{ position: 10 }] }
+  BookingDate;
+
+  @UI: { lineItem: [{ position: 20 }], identification: [{ position: 20 }] }
+  CarrierID;
+
+  @UI: { lineItem: [{ position: 30 }], identification: [{ position: 30 }] }
+  ConnectionID;
+
+  @UI: { lineItem: [{ position: 40 }], identification: [{ position: 40 }] }
+  FlightDate;
+
+  @UI: { lineItem: [{ position: 50 }], identification: [{ position: 50 }] }
+  FlightPrice;
+}
+```
+
+## Rules
+- CDS view MUST have `@Metadata.allowExtensions: true`
+- Metadata Extension annotates **projection CDS** (ZC_*), not interface (ZI_*)
+- `@Metadata.layer: #CORE` is the standard for application development
+- Number positions by 10s for easy insertion
+- `@UI.facet` goes on the FIRST field (or any field — it's entity-level)
+- `parentId` links sub-facets to a `#COLLECTION` facet
+- `targetElement` for child tables matches the association name (e.g., `_Booking`)
+- `targetQualifier` matches the `qualifier` in `@UI.fieldGroup`
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| UI annotations in interface CDS (ZI_*) | Metadata Extension on projection (ZC_*) |
+| Missing `@Metadata.allowExtensions` on CDS | Extension silently ignored |
+| `@UI.facet` with `targetElement` that doesn't match association name | Use exact association name |
+| Positions 1, 2, 3 | Use 10, 20, 30 for insertion gaps |
+| Actions in `@UI.fieldGroup` | Actions in `@UI.lineItem` or `@UI.identification` with `type: #FOR_ACTION` |
+| `#FIELDGROUP_REFERENCE` without matching `targetQualifier` | Qualifier must match `@UI.fieldGroup` qualifier |
+| Multiple `@UI.facet` on different fields | Put all facets in ONE `@UI.facet` array on one field |

package/dist/knowledge/cap/authentication.md

@@ -0,0 +1,278 @@
+# CAP Authentication — XSUAA, roles, scopes, instance-level auth
+
+## Enable Authentication
+
+```json
+// package.json
+{
+  "cds": {
+    "requires": {
+      "auth": {
+        "kind": "xsuaa",
+        "[development]": {
+          "kind": "mocked",
+          "users": {
+            "admin": { "password": "admin", "roles": ["admin", "viewer"] },
+            "viewer": { "password": "viewer", "roles": ["viewer"] },
+            "carol": { "password": "carol", "roles": [], "attr": { "Country": "DE" } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Service-Level Access Control
+
+```cds
+// Entire service requires authentication
+service AdminService @(requires: 'admin') {
+  entity Books as projection on my.Books;
+  entity Authors as projection on my.Authors;
+}
+
+// Public read, auth for write
+service CatalogService @(requires: 'authenticated-user') {
+  @readonly
+  entity Books as projection on my.Books;
+}
+
+// No auth (public API)
+service PublicService {
+  @readonly
+  entity Products as projection on my.Products;
+}
+```
+
+## Entity-Level Access Control
+
+```cds
+service OrderService {
+  // Only admin can manage orders
+  @requires: 'admin'
+  entity Orders as projection on my.Orders;
+
+  // Multiple roles (any matches)
+  @requires: ['admin', 'support']
+  action cancelAllOrders();
+
+  // Read-only for authenticated users
+  @readonly @requires: 'authenticated-user'
+  entity Products as projection on my.Products;
+}
+```
+
+## Instance-Level Access (Row-Based)
+
+```cds
+// Restrict based on user role + attributes
+annotate OrderService.Orders with @(restrict: [
+  // Admin: full access
+  { grant: '*', to: 'admin' },
+
+  // Viewer: read only
+  { grant: 'READ', to: 'viewer' },
+
+  // Support: read + update
+  { grant: ['READ', 'UPDATE'], to: 'support' },
+
+  // Country-based: only see orders from user's country
+  { grant: 'READ', where: 'country = $user.Country' },
+
+  // Own records: user sees only what they created
+  { grant: 'READ', where: 'createdBy = $user' },
+
+  // Combined: role + attribute
+  { grant: ['READ', 'UPDATE'], to: 'regional_admin',
+    where: 'country = $user.Country' }
+]);
+```
+
+## xs-security.json — Scopes and Roles
+
+```json
+{
+  "xsappname": "myapp",
+  "tenant-mode": "dedicated",
+  "scopes": [
+    { "name": "$XSAPPNAME.admin", "description": "Admin" },
+    { "name": "$XSAPPNAME.viewer", "description": "Viewer" },
+    { "name": "$XSAPPNAME.support", "description": "Support" }
+  ],
+  "attributes": [
+    { "name": "Country", "description": "Country", "valueType": "string" },
+    { "name": "CostCenter", "description": "Cost Center", "valueType": "string" }
+  ],
+  "role-templates": [
+    {
+      "name": "Admin",
+      "description": "Full access",
+      "scope-references": ["$XSAPPNAME.admin", "$XSAPPNAME.viewer"]
+    },
+    {
+      "name": "Viewer",
+      "description": "Read-only",
+      "scope-references": ["$XSAPPNAME.viewer"]
+    },
+    {
+      "name": "RegionalAdmin",
+      "description": "Admin for specific country",
+      "scope-references": ["$XSAPPNAME.admin"],
+      "attribute-references": ["Country"]
+    }
+  ],
+  "role-collections": [
+    {
+      "name": "MyApp_Admin",
+      "role-template-references": ["$XSAPPNAME.Admin"]
+    },
+    {
+      "name": "MyApp_Viewer",
+      "role-template-references": ["$XSAPPNAME.Viewer"]
+    }
+  ]
+}
+```
+
+## Accessing User Info in Handlers
+
+```js
+this.before('*', (req) => {
+  const { user } = req;
+
+  // User ID
+  console.log(user.id);          // 'admin@company.com'
+
+  // Role check
+  if (user.is('admin')) { /* full access */ }
+  if (user.is('viewer')) { /* read only */ }
+
+  // User attributes
+  const country = user.attr.Country;    // 'DE'
+  const costCenter = user.attr.CostCenter;
+
+  // Tenant
+  console.log(req.tenant);      // 't1' (multi-tenant)
+
+  // Locale
+  console.log(req.locale);      // 'en'
+});
+```
+
+## Custom Authorization in Handler
+
+```js
+this.before('UPDATE', 'Orders', async (req) => {
+  // Only order owner or admin can update
+  const order = await SELECT.one.from('Orders', req.data.ID);
+  if (!order) return req.reject(404, 'Order not found');
+
+  if (order.createdBy !== req.user.id && !req.user.is('admin')) {
+    return req.reject(403, 'Only the order creator or admin can modify this order');
+  }
+});
+
+this.before('DELETE', 'Orders', async (req) => {
+  // Admin only
+  if (!req.user.is('admin')) {
+    return req.reject(403, 'Only administrators can delete orders');
+  }
+});
+
+// Attribute-based filtering
+this.before('READ', 'Orders', (req) => {
+  if (!req.user.is('admin')) {
+    // Non-admin users only see their country's orders
+    const country = req.user.attr.Country;
+    if (country) {
+      req.query.where({ country });
+    }
+  }
+});
+```
+
+## Mock Users for Development
+
+```json
+// package.json — mocked auth
+{
+  "cds": {
+    "requires": {
+      "auth": {
+        "[development]": {
+          "kind": "mocked",
+          "users": {
+            "alice": {
+              "password": "alice",
+              "roles": ["admin", "viewer"],
+              "attr": { "Country": "DE" }
+            },
+            "bob": {
+              "password": "bob",
+              "roles": ["viewer"],
+              "attr": { "Country": "US" }
+            }
+          }
+        },
+        "[production]": {
+          "kind": "xsuaa"
+        }
+      }
+    }
+  }
+}
+```
+
+```bash
+# Test with mock user
+curl -u alice:alice http://localhost:4004/admin/Books
+
+# Or in browser: login prompt with alice/alice
+```
+
+## Mapping CDS Roles to XSUAA Scopes
+
+| CDS `@requires` | xs-security.json scope |
+|---|---|
+| `'admin'` | `$XSAPPNAME.admin` |
+| `'viewer'` | `$XSAPPNAME.viewer` |
+| `'authenticated-user'` | Any valid JWT token (built-in) |
+| `'system-user'` | Technical user (built-in) |
+
+CAP auto-maps: `@requires: 'admin'` → checks for scope `$XSAPPNAME.admin` in JWT.
+
+## BTP Role Collection Assignment
+
+```bash
+# After deployment, assign users to role collections in BTP Cockpit:
+# 1. BTP Cockpit → Subaccount → Security → Role Collections
+# 2. Select "MyApp_Admin"
+# 3. Add user: alice@company.com
+# 4. Save
+
+# Or via CLI:
+cf create-service-key myapp-auth myapp-auth-key
+```
+
+## Rules
+- `@requires: 'authenticated-user'` for any logged-in user
+- `@requires: 'admin'` maps to scope `$XSAPPNAME.admin` in xs-security.json
+- `@restrict` for instance-level (row-based) authorization
+- `$user` in `where` clause resolves to `req.user.id`
+- `$user.Country` resolves to user attribute `Country`
+- Mock users in `[development]` profile — XSUAA in `[production]`
+- Role collections assigned in BTP Cockpit after deployment
+- Always test with mock users before deploying to BTP
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| Hardcoded user checks in handler | Use `@requires` + `@restrict` declaratively |
+| `@requires` on service but sensitive entities open | Add `@requires` on entity level too |
+| Missing `[production]` XSUAA config | Mocked auth in production = no security |
+| `$XSAPPNAME.admin` hardcoded in handler | Use `req.user.is('admin')` |
+| No mock users in development | Define mock users for local testing |
+| Role collection without role template | Role collections reference role templates |
+| Checking `req.user` without auth middleware | Ensure `"auth"` is in `cds.requires` |
+| Missing `forwardAuthToken` in App Router | Auth token not propagated to CAP server |