@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/fiori/annotations.md

@@ -0,0 +1,347 @@
+# Fiori Annotations — XML and CDS Reference
+
+## XML Annotation File Setup
+
+```json
+// manifest.json — dataSources configuration
+{
+    "sap.app": {
+        "dataSources": {
+            "mainService": {
+                "uri": "/sap/opu/odata/sap/SERVICE/",
+                "type": "OData",
+                "settings": {
+                    "localUri": "localService/metadata.xml",
+                    "annotations": ["annotation"]
+                }
+            },
+            "annotation": {
+                "type": "ODataAnnotation",
+                "uri": "annotations/annotation.xml"
+            }
+        }
+    }
+}
+```
+
+File location: `webapp/annotations/annotation.xml`
+
+Prerequisites: local metadata.xml copy, single `EntityContainer`, valid `<edmx:DataServices/Schema>` nodes.
+
+## LineItem — Table Columns
+
+```xml
+<Annotations Target="Namespace.EntityType">
+    <Annotation Term="UI.LineItem">
+        <Collection>
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" Path="PropertyName"/>
+                <PropertyValue Property="Label" String="Column Label"/>
+            </Record>
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" Path="Price"/>
+                <PropertyValue Property="Criticality" Path="PriceCriticality"/>
+            </Record>
+            <Record Type="UI.DataFieldForAnnotation">
+                <PropertyValue Property="Target" AnnotationPath="@UI.DataPoint#Rating"/>
+                <PropertyValue Property="Label" String="Rating"/>
+            </Record>
+            <Record Type="UI.DataFieldForAction">
+                <PropertyValue Property="Label" String="Approve"/>
+                <PropertyValue Property="Action" String="Namespace.Approve"/>
+            </Record>
+        </Collection>
+    </Annotation>
+</Annotations>
+```
+
+## SelectionFields — Filter Bar
+
+```xml
+<Annotation Term="UI.SelectionFields">
+    <Collection>
+        <PropertyPath>Property1</PropertyPath>
+        <PropertyPath>Property2</PropertyPath>
+        <PropertyPath>Property3</PropertyPath>
+    </Collection>
+</Annotation>
+```
+
+## HeaderInfo — Object Page Title Area
+
+```xml
+<Annotation Term="UI.HeaderInfo">
+    <Record Type="UI.HeaderInfoType">
+        <PropertyValue Property="TypeName" String="Sales Order"/>
+        <PropertyValue Property="TypeNamePlural" String="Sales Orders"/>
+        <PropertyValue Property="Title">
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" Path="OrderID"/>
+            </Record>
+        </PropertyValue>
+        <PropertyValue Property="Description">
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" Path="CustomerName"/>
+            </Record>
+        </PropertyValue>
+        <PropertyValue Property="ImageUrl" Path="ProductImage"/>
+    </Record>
+</Annotation>
+```
+
+## Facets — Object Page Sections
+
+```xml
+<Annotation Term="UI.Facets">
+    <Collection>
+        <!-- Grouped section with sub-facets -->
+        <Record Type="UI.CollectionFacet">
+            <PropertyValue Property="Label" String="General"/>
+            <PropertyValue Property="ID" String="GeneralSection"/>
+            <PropertyValue Property="Facets">
+                <Collection>
+                    <Record Type="UI.ReferenceFacet">
+                        <PropertyValue Property="Target"
+                            AnnotationPath="@UI.FieldGroup#Basic"/>
+                    </Record>
+                    <Record Type="UI.ReferenceFacet">
+                        <PropertyValue Property="Target"
+                            AnnotationPath="@UI.FieldGroup#Dates"/>
+                    </Record>
+                </Collection>
+            </PropertyValue>
+        </Record>
+        <!-- Navigation property table section -->
+        <Record Type="UI.ReferenceFacet">
+            <PropertyValue Property="Label" String="Items"/>
+            <PropertyValue Property="ID" String="ItemsSection"/>
+            <PropertyValue Property="Target"
+                AnnotationPath="to_Items/@UI.LineItem"/>
+        </Record>
+    </Collection>
+</Annotation>
+```
+
+## FieldGroup — Grouped Form Fields
+
+```xml
+<Annotation Term="UI.FieldGroup" Qualifier="Basic">
+    <Record Type="UI.FieldGroupType">
+        <PropertyValue Property="Data">
+            <Collection>
+                <Record Type="UI.DataField">
+                    <PropertyValue Property="Value" Path="OrderID"/>
+                </Record>
+                <Record Type="UI.DataField">
+                    <PropertyValue Property="Value" Path="Status"/>
+                    <PropertyValue Property="Criticality" Path="StatusCriticality"/>
+                </Record>
+                <Record Type="UI.DataFieldWithUrl">
+                    <PropertyValue Property="Value" Path="WebsiteUrl"/>
+                    <PropertyValue Property="Url" Path="WebsiteUrl"/>
+                </Record>
+            </Collection>
+        </PropertyValue>
+    </Record>
+</Annotation>
+```
+
+## DataPoint — KPI / Header Values
+
+```xml
+<Annotation Term="UI.DataPoint" Qualifier="Revenue">
+    <Record Type="UI.DataPointType">
+        <PropertyValue Property="Value" Path="TotalRevenue"/>
+        <PropertyValue Property="Title" String="Revenue"/>
+        <PropertyValue Property="Criticality" Path="RevenueCriticality"/>
+        <PropertyValue Property="TargetValue" Path="RevenueTarget"/>
+        <PropertyValue Property="Visualization"
+            EnumMember="UI.VisualizationType/Progress"/>
+    </Record>
+</Annotation>
+```
+
+## ValueList — Value Help (F4)
+
+```xml
+<Annotations Target="Namespace.EntityType/CategoryID">
+    <Annotation Term="Common.ValueList">
+        <Record Type="Common.ValueListType">
+            <PropertyValue Property="CollectionPath" String="Categories"/>
+            <PropertyValue Property="Parameters">
+                <Collection>
+                    <Record Type="Common.ValueListParameterInOut">
+                        <PropertyValue Property="LocalDataProperty"
+                            PropertyPath="CategoryID"/>
+                        <PropertyValue Property="ValueListProperty" String="ID"/>
+                    </Record>
+                    <Record Type="Common.ValueListParameterDisplayOnly">
+                        <PropertyValue Property="ValueListProperty"
+                            String="Description"/>
+                    </Record>
+                </Collection>
+            </PropertyValue>
+        </Record>
+    </Annotation>
+</Annotations>
+```
+
+## Common.Text — Display Text for Coded Values
+
+```xml
+<Annotations Target="Namespace.EntityType/StatusCode">
+    <Annotation Term="Common.Text" Path="StatusText"/>
+    <Annotation Term="Common.TextArrangement"
+        EnumMember="UI.TextArrangementType/TextFirst"/>
+</Annotations>
+```
+
+## Chart
+
+```xml
+<Annotation Term="UI.Chart" Qualifier="SalesChart">
+    <Record Type="UI.ChartDefinitionType">
+        <PropertyValue Property="Title" String="Sales Overview"/>
+        <PropertyValue Property="ChartType" EnumMember="UI.ChartType/Column"/>
+        <PropertyValue Property="Dimensions">
+            <Collection><PropertyPath>Region</PropertyPath></Collection>
+        </PropertyValue>
+        <PropertyValue Property="DimensionAttributes">
+            <Collection>
+                <Record Type="UI.ChartDimensionAttributeType">
+                    <PropertyValue Property="Dimension" PropertyPath="Region"/>
+                    <PropertyValue Property="Role"
+                        EnumMember="UI.ChartDimensionRoleType/Category"/>
+                </Record>
+            </Collection>
+        </PropertyValue>
+        <PropertyValue Property="Measures">
+            <Collection><PropertyPath>Amount</PropertyPath></Collection>
+        </PropertyValue>
+        <PropertyValue Property="MeasureAttributes">
+            <Collection>
+                <Record Type="UI.ChartMeasureAttributeType">
+                    <PropertyValue Property="Measure" PropertyPath="Amount"/>
+                    <PropertyValue Property="Role"
+                        EnumMember="UI.ChartMeasureRoleType/Axis1"/>
+                </Record>
+            </Collection>
+        </PropertyValue>
+    </Record>
+</Annotation>
+```
+
+## CDS Equivalents (CAP)
+
+```cds
+annotate CatalogService.Orders with @(
+    UI: {
+        SelectionFields: [ status, customer, createdAt ],
+        LineItem: [
+            { Value: orderNo },
+            { Value: customer, Label: 'Customer' },
+            { Value: totalAmount },
+            { Value: status, Criticality: statusCriticality },
+            { $Type: 'UI.DataFieldForAction', Action: 'approve', Label: 'Approve' }
+        ],
+        HeaderInfo: {
+            TypeName: 'Order',
+            TypeNamePlural: 'Orders',
+            Title: { Value: orderNo },
+            Description: { Value: customer }
+        },
+        Facets: [
+            {
+                $Type: 'UI.CollectionFacet', ID: 'General', Label: 'General',
+                Facets: [
+                    { $Type: 'UI.ReferenceFacet', Target: '@UI.FieldGroup#Main' }
+                ]
+            },
+            { $Type: 'UI.ReferenceFacet', Target: 'items/@UI.LineItem', Label: 'Items' }
+        ],
+        FieldGroup#Main: {
+            Data: [
+                { Value: orderNo },
+                { Value: status, Criticality: statusCriticality },
+                { Value: totalAmount }
+            ]
+        }
+    }
+);
+
+// Value help
+annotate CatalogService.Orders with {
+    status @Common.ValueList: {
+        CollectionPath: 'StatusCodes',
+        Parameters: [
+            { $Type: 'Common.ValueListParameterInOut', LocalDataProperty: status,
+              ValueListProperty: 'code' },
+            { $Type: 'Common.ValueListParameterDisplayOnly',
+              ValueListProperty: 'description' }
+        ]
+    };
+    status @Common.Text: statusText @Common.TextArrangement: #TextFirst;
+};
+```
+
+## Vocabulary Quick Reference
+
+| Annotation | Purpose |
+|---|---|
+| `UI.LineItem` | Table columns |
+| `UI.SelectionFields` | Filter bar fields |
+| `UI.HeaderInfo` | Object page title/subtitle |
+| `UI.HeaderFacets` | Object page header KPIs |
+| `UI.Facets` | Object page sections |
+| `UI.FieldGroup#Qualifier` | Form field grouping |
+| `UI.DataPoint#Qualifier` | KPI / progress / rating |
+| `UI.Chart` | Chart definition |
+| `UI.PresentationVariant` | Default sort + visualization |
+| `UI.SelectionVariant` | Default filter values |
+| `UI.Identification` | Object page footer actions |
+| `Common.Label` | Property display label |
+| `Common.Text` | Display text for code/ID fields |
+| `Common.TextArrangement` | Text display order (TextFirst, TextOnly) |
+| `Common.ValueList` | Value help / F4 |
+| `Common.SemanticObject` | Intent-based navigation target |
+| `Common.DraftRoot` | Draft handling root entity |
+| `Capabilities.InsertRestrictions` | Create permission |
+| `Capabilities.UpdateRestrictions` | Edit permission |
+| `Capabilities.DeleteRestrictions` | Delete permission |
+| `Capabilities.FilterRestrictions` | Filter limitations |
+
+## Criticality Values
+
+| Value | CDS | Rendering |
+|---|---|---|
+| 0 | `Neutral` | Grey (default) |
+| 1 | `Negative` | Red (error) |
+| 2 | `Critical` | Orange (warning) |
+| 3 | `Positive` | Green (success) |
+| 5 | `Information` | Blue (info) |
+
+## Rules
+
+- Local annotation files override backend annotations (same term + qualifier + target)
+- Annotation file must be referenced in `manifest.json` `dataSources.*.settings.annotations`
+- Use `Qualifier` to define multiple instances of same annotation term (e.g., `FieldGroup#Basic`, `FieldGroup#Dates`)
+- `Path` resolves at runtime from entity data; `String` is static text
+- `PropertyPath` is used inside `Collection` elements; `Path` is used inside `Record` property values
+- `AnnotationPath` navigates to other annotations (e.g., `@UI.FieldGroup#Basic`)
+- Navigation properties in annotation paths use `/` separator: `to_Items/@UI.LineItem`
+- Always pair `Common.Text` with `Common.TextArrangement` for readable ID fields
+- i18n keys: use camelCase for non-CAP, PascalCase for CAP projects
+- Handle i18n externalization near project end to minimize unused entries
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| Editing backend annotation files directly | Create local annotation overrides |
+| Missing `Common.Text` on code/ID fields | Always add `Text` + `TextArrangement` |
+| Using `String` for dynamic values | Use `Path` to bind to entity properties |
+| Omitting `Qualifier` on multiple FieldGroups | Each FieldGroup needs unique qualifier |
+| Putting actions in `UI.FieldGroup` | Use `UI.DataFieldForAction` in `LineItem` or `Identification` |
+| Defining ValueList without `InOut` parameter | At least one `ValueListParameterInOut` required |
+| Annotations in metadata.xml directly | Use separate annotation.xml files |
+| Ignoring diagnostics warnings in IDE | Fix all warnings before deployment |

package/dist/knowledge/fiori/deployment.md

@@ -0,0 +1,340 @@
+# Fiori Deployment — ABAP and Cloud Foundry
+
+## ABAP Deployment — ui5-deploy.yaml
+
+```yaml
+specVersion: "2.4"
+metadata:
+  name: project-name
+type: application
+builder:
+  resources:
+    excludes:
+      - /test/**
+      - /localService/**
+deploy:
+  target:
+    url: https://system.example.com
+    client: "100"
+    scp: false
+    params:
+      sap-language: EN
+  app:
+    name: ZAPP_NAME
+    package: ZPACKAGE
+    description: Application description
+    transport: DEVK900123
+```
+
+```json
+// package.json — deploy script
+{
+    "scripts": {
+        "deploy": "fiori deploy --config ui5-deploy.yaml"
+    }
+}
+```
+
+```bash
+# Generate deploy config
+npx fiori add deploy-config
+
+# Execute deployment
+npm run deploy
+
+# Undeploy
+npx fiori undeploy --config ui5-deploy.yaml
+
+# Debug deployment issues
+DEBUG=ux-odata-client npm run deploy
+```
+
+### ABAP Prerequisites
+
+| Requirement | Minimum |
+|---|---|
+| SAP_UI Component | 7.53+ |
+| ABAP Repository Service | `/sap/opu/odata/UI5/ABAP_REPOSITORY_SRV` active |
+| Authorization | `S_DEVELOP` with required activities |
+| Transport | Required unless `$TMP` / local package |
+
+### Authentication
+
+| Method | On-Premise | BTP ABAP |
+|---|---|---|
+| Basic Auth | Yes | No |
+| Reentrance Ticket | No | Yes |
+| OAuth 2.0 | No | Deprecated |
+
+## Cloud Foundry Deployment — mta.yaml
+
+```yaml
+_schema-version: "3.2"
+ID: project-name
+version: 0.0.1
+modules:
+  - name: project-name-destination-content
+    type: com.sap.application.content
+    requires:
+      - name: project-name-destination-service
+        parameters:
+          content-target: true
+      - name: project-name-repo-host
+        parameters:
+          service-key:
+            name: project-name-repo-host-key
+      - name: project-name-uaa
+        parameters:
+          service-key:
+            name: project-name-uaa-key
+    parameters:
+      content:
+        instance:
+          destinations:
+            - Name: project-name-repo-host
+              ServiceInstanceName: project-name-html5-srv
+              ServiceKeyName: project-name-repo-host-key
+              sap.cloud.service: project-name
+            - Authentication: OAuth2UserTokenExchange
+              Name: project-name-uaa
+              ServiceInstanceName: project-name-xsuaa
+              ServiceKeyName: project-name-uaa-key
+              sap.cloud.service: project-name
+          existing_destinations_policy: update
+
+  - name: project-name
+    type: html5
+    path: .
+    build-parameters:
+      build-result: dist
+      builder: custom
+      commands:
+        - npm install
+        - npm run build:cf
+
+resources:
+  - name: project-name-repo-host
+    type: org.cloudfoundry.managed-service
+    parameters:
+      service: html5-apps-repo
+      service-plan: app-host
+  - name: project-name-destination-service
+    type: org.cloudfoundry.managed-service
+    parameters:
+      service: destination
+      service-plan: lite
+  - name: project-name-uaa
+    type: org.cloudfoundry.managed-service
+    parameters:
+      service: xsuaa
+      service-plan: application
+      config:
+        xsappname: project-name
+        tenant-mode: dedicated
+```
+
+### xs-app.json — App Router
+
+```json
+{
+    "welcomeFile": "/index.html",
+    "authenticationMethod": "route",
+    "routes": [
+        {
+            "source": "^/sap/opu/odata/(.*)$",
+            "target": "/sap/opu/odata/$1",
+            "destination": "backend-destination",
+            "authenticationType": "xsuaa"
+        },
+        {
+            "source": "^(.*)$",
+            "target": "$1",
+            "service": "html5-apps-repo-rt",
+            "authenticationType": "xsuaa"
+        }
+    ]
+}
+```
+
+```bash
+# CF prerequisites
+npm install -g mta
+cf install-plugin -r CF-Community "multiapps"
+
+# Build MTA archive
+mbt build
+
+# Deploy to CF
+cf deploy mta_archives/project-name_0.0.1.mtar
+
+# Undeploy from CF
+cf undeploy project-name --delete-services
+```
+
+## Fiori Launchpad Configuration
+
+```json
+// manifest.json — crossNavigation inbound
+{
+    "sap.app": {
+        "crossNavigation": {
+            "inbounds": {
+                "intent1": {
+                    "semanticObject": "Product",
+                    "action": "display",
+                    "title": "{{appTitle}}",
+                    "subTitle": "{{appSubTitle}}",
+                    "signature": {
+                        "parameters": {},
+                        "additionalParameters": "allowed"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+```bash
+# Generate FLP config
+npx fiori add flp-config
+```
+
+| Parameter | Description | Example |
+|---|---|---|
+| Semantic Object | Business object identifier | `SalesOrder`, `Product` |
+| Action | Navigation verb | `display`, `manage`, `create` |
+| Title | Launchpad tile title | `Manage Products` |
+| Subtitle | Tile subtitle (optional) | `Product Administration` |
+
+## Complete manifest.json — Data Sources
+
+```json
+{
+    "sap.app": {
+        "id": "com.mycompany.products",
+        "type": "application",
+        "applicationVersion": { "version": "1.0.0" },
+        "dataSources": {
+            "mainService": {
+                "uri": "/sap/opu/odata/sap/PRODUCT_SRV/",
+                "type": "OData",
+                "settings": {
+                    "annotations": ["annotation"],
+                    "localUri": "localService/metadata.xml",
+                    "odataVersion": "2.0"
+                }
+            },
+            "annotation": {
+                "type": "ODataAnnotation",
+                "uri": "annotations/annotation.xml",
+                "settings": {
+                    "localUri": "annotations/annotation.xml"
+                }
+            }
+        }
+    },
+    "sap.ui5": {
+        "dependencies": {
+            "minUI5Version": "1.120.0",
+            "libs": { "sap.fe.templates": {} }
+        },
+        "models": {
+            "i18n": {
+                "type": "sap.ui.model.resource.ResourceModel",
+                "settings": {
+                    "bundleName": "com.mycompany.products.i18n.i18n"
+                }
+            },
+            "": {
+                "dataSource": "mainService",
+                "preload": true,
+                "settings": {
+                    "defaultBindingMode": "TwoWay",
+                    "defaultCountMode": "Inline",
+                    "refreshAfterChange": false
+                }
+            }
+        }
+    },
+    "sap.fiori": {
+        "registrationIds": [],
+        "archeType": "transactional"
+    }
+}
+```
+
+## Required OData Services (ABAP)
+
+| Service | Path |
+|---|---|
+| SAPUI5 Repository | `/sap/opu/odata/UI5/ABAP_REPOSITORY_SRV` |
+| OData V2 Catalog | `/sap/opu/odata/IWFND/CATALOGSERVICE;v=2` |
+| OData V4 Catalog (dev) | `/sap/opu/odata4/iwfnd/config/default/iwfnd/catalog/0001` |
+| OData V4 Catalog (prod) | `/sap/opu/odata4/iwfnd/config/default/iwfnd/catalog/0002` |
+| ATO Settings | `/sap/bc/adt/ato/settings` |
+
+## Transport Request Options
+
+| Option | When to Use |
+|---|---|
+| Enter manually | Known transport ID |
+| Choose from existing | Browse system transports |
+| Create new | Generate during config |
+| Create during deployment | Auto-create on first deploy |
+
+## Project Structure (CF)
+
+```
+project/
+├── webapp/
+│   ├── manifest.json
+│   ├── annotations/
+│   │   └── annotation.xml
+│   └── i18n/
+│       └── i18n.properties
+├── mta.yaml
+├── xs-app.json
+├── xs-security.json
+├── ui5.yaml
+├── ui5-deploy.yaml
+└── package.json
+```
+
+## Rules
+
+- Always exclude `/test/**` and `/localService/**` from deployment builds
+- ABAP app name (`ZAPP_NAME`) must follow customer namespace (Z/Y prefix)
+- Package must exist before deployment; transport must be modifiable
+- For BTP ABAP, use reentrance tickets (not basic auth)
+- CF deployment requires `mta` CLI v1.0+ and `multiapps` CF plugin
+- Set `scp: false` for on-premise ABAP; `scp: true` for BTP ABAP Environment
+- `crossNavigation.inbounds` is required for Fiori Launchpad tile registration
+- Semantic object + action must be unique across the Fiori Launchpad
+- Use `odataVersion: "2.0"` or `"4.0"` explicitly in dataSources settings
+- `existing_destinations_policy: update` in mta.yaml prevents destination conflicts on redeploy
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| Deploying without transport in non-local package | Always assign modifiable transport request |
+| Using basic auth for BTP ABAP | Use reentrance tickets |
+| Missing `localUri` for metadata | Always provide local metadata copy |
+| Deploying test files to production | Exclude `/test/**` in builder resources |
+| Hardcoding service URL in xs-app.json | Use BTP destination name |
+| Omitting `crossNavigation` for launchpad apps | Add FLP config before deployment |
+| Skipping `multiapps` plugin for CF deploy | Install: `cf install-plugin -r CF-Community "multiapps"` |
+| Using `scp: true` for on-premise systems | Set `scp: false` for on-premise ABAP |
+| Missing `html5-apps-repo` resource in mta.yaml | Required for HTML5 repository hosting |
+| Deploying without checking `/IWFND/ERROR_LOG` on failures | Always check error log for 400 errors |
+
+## Troubleshooting
+
+| Issue | Check |
+|---|---|
+| Service activation error | SAP_UI 7.53+ installed? |
+| HTTP 400 on deploy | `/IWFND/ERROR_LOG` in SAP GUI |
+| Virus scan failure | `/IWFND/VIRUS_SCAN` config |
+| Authorization error | `S_DEVELOP` authorization object |
+| CF deploy fails | `cf login` active? `multiapps` plugin installed? |