orbit-code-ai 0.1.0

package/_agent_reference/config/naming-conventions.md

@@ -0,0 +1,188 @@
+# Naming Conventions
+
+All naming in this framework follows strict conventions. The agent MUST follow these when generating any new code, files, or scripts.
+
+---
+
+## ESQL Broker Schema
+
+```esql
+BROKER SCHEMA Qiwa.<ApplicationName>
+-- Examples:
+BROKER SCHEMA Qiwa.BS_Account
+BROKER SCHEMA Qiwa.BS_Transfer
+BROKER SCHEMA Qiwa.Framework.Lib   ← shared lib only, never use for app code
+```
+
+---
+
+## ESQL Module Naming
+
+```
+<FlowName>_<Purpose>.esql
+
+Purpose conventions:
+  _Compute          ← main business logic, validation, routing
+  _PrepareRequest   ← format outgoing backend request
+  _MapResponse      ← map backend response to ESB format
+  _PrepareAudit     ← prepare audit-specific data
+  _Filter           ← boolean filter/routing conditions
+  _IsXxx            ← boolean check (returns TRUE/FALSE)
+  _SetXxx           ← setter (modifies state)
+
+Examples:
+  GetAccountDetails_Compute.esql
+  GetAccountDetails_PrepareRequest.esql
+  GetAccountDetails_MapResponse.esql
+  MQ_Input_Node_IsAuditEnabled.esql
+  ErrorHandler_IsExceptionCaught.esql
+```
+
+---
+
+## Message Flow Naming
+
+```
+<FlowName>.msgflow
+
+FlowName = PascalCase, verb-first, descriptive
+Examples:
+  GetAccountDetails.msgflow
+  SearchCustomerTransactions.msgflow
+  CreateBeneficiary.msgflow
+  UpdateAccountNickname.msgflow
+  ProcessBatchFile.msgflow
+```
+
+---
+
+## Application / Project Naming
+
+```
+<Tier>_<Domain>
+Tier:    BS (Business Service) | ESB (Enterprise Service Bus)
+Domain:  PascalCase domain name
+
+Examples:
+  BS_Account
+  BS_Transfer
+  BS_Beneficiaries
+  ESB_Common
+```
+
+---
+
+## Properties File Naming
+
+```
+<DOMAIN>-PROPERTIES.xml    (ALL-CAPS domain)
+Examples:
+  ACCOUNT-PROPERTIES.xml
+  TRANSFER-PROPERTIES.xml
+  BENEFICIARIES-PROPERTIES.xml
+```
+
+## Properties Group Naming
+
+```
+Group name = {ApplicationLabel}.{FlowName}
+Examples:
+  BS_Account.GetAccountDetails
+  BS_Transfer.CreateTransfer
+  BS_Beneficiaries.SearchBeneficiaries
+```
+
+---
+
+## Queue Naming
+
+```
+<Tier>.<VERB>.<DOMAIN>.<RESOURCE>.<QUALIFIER>.<TYPE>
+
+Tier:      BS | ESB
+VERB:      GET | SEARCH | CREATE | UPDATE | DELETE | PROCESS  (ALL-CAPS)
+DOMAIN:    domain name in ALL-CAPS
+RESOURCE:  resource name in ALL-CAPS
+QUALIFIER: additional context in ALL-CAPS (optional)
+TYPE:      RQ (request) | RS (response)
+
+Dead letter: append .BACKOUT to the primary queue name
+
+Examples:
+  BS.GET.CUSTOMER.ACCOUNT.DETAILS.RQ
+  BS.GET.CUSTOMER.ACCOUNT.DETAILS.RS
+  BS.GET.CUSTOMER.ACCOUNT.DETAILS.RQ.BACKOUT
+  BS.SEARCH.CUST.ACCT.LASTN.TRAN.RQ
+  ESB.COMMON.UPDATE.CUSTOMER.ACCOUNT.NICKNAME.RQ
+```
+
+---
+
+## Queue/Shell Script Naming
+
+```
+<DOMAIN>QueuesDefinition.sh    (ALL-CAPS domain)
+Examples:
+  ACCOUNTQueuesDefinition.sh
+  TRANSFERQueuesDefinition.sh
+  BENEFICIARIESQueuesDefinition.sh
+```
+
+## DB Script Naming
+
+```
+<DOMAIN>DBScript.sql    (ALL-CAPS domain)
+Examples:
+  ACCOUNTDBScript.sql
+  TRANSFERDBScript.sql
+```
+
+---
+
+## ESBFUNCID (Service Identifier in DB)
+
+```
+Format: <ABBREV><SEQ>
+ABBREV: 4-char uppercase abbreviation of service name
+SEQ:    4-digit sequence starting at 0001
+
+Examples:
+  ACCD0001  ← Account Details
+  TRFR0001  ← Transfer Request
+  BNFD0001  ← Beneficiary Details
+  SRCH0001  ← Search operation
+```
+
+Must be unique across ALL services in `MCR_CHANNESBFUNC_TBL`.
+
+---
+
+## Subflow Terminal Naming
+
+Standard terminal names used in the framework:
+
+| Terminal | Meaning |
+|---|---|
+| `out` | Success path |
+| `failure` | Exception / error path → always wire to ErrorHandler |
+| `true` | Filter condition matched |
+| `false` | Filter condition not matched |
+
+---
+
+## Summary Table
+
+| Artifact | Format | Example |
+|---|---|---|
+| ESQL schema | `Qiwa.<AppName>` | `Qiwa.BS_Account` |
+| ESQL module | `<Flow>_<Purpose>.esql` | `GetAccountDetails_Compute.esql` |
+| Message flow | `<FlowName>.msgflow` | `GetAccountDetails.msgflow` |
+| Application | `<Tier>_<Domain>` | `BS_Account` |
+| Properties file | `<DOMAIN>-PROPERTIES.xml` | `ACCOUNT-PROPERTIES.xml` |
+| Properties group | `<AppLabel>.<FlowName>` | `BS_Account.GetAccountDetails` |
+| Request queue | `<Tier>.<VERB>.<DOMAIN>.<RES>.RQ` | `BS.GET.CUSTOMER.ACCOUNT.DETAILS.RQ` |
+| Response queue | `<Tier>.<VERB>.<DOMAIN>.<RES>.RS` | `BS.GET.CUSTOMER.ACCOUNT.DETAILS.RS` |
+| Backout queue | `<QUEUE_NAME>.BACKOUT` | `BS.GET.CUSTOMER.ACCOUNT.DETAILS.RQ.BACKOUT` |
+| Queue script | `<DOMAIN>QueuesDefinition.sh` | `ACCOUNTQueuesDefinition.sh` |
+| DB script | `<DOMAIN>DBScript.sql` | `ACCOUNTDBScript.sql` |
+| ESBFUNCID | `<ABBREV><4-digit-seq>` | `ACCD0001` |

package/_agent_reference/config/properties-template.md

@@ -0,0 +1,158 @@
+# Properties File Template
+
+Every application has one XML properties file loaded by `PropertyReader`. The file lives in the Framework root alongside other `*-PROPERTIES.xml` files.
+
+---
+
+## File Naming
+
+```
+<DOMAIN>-PROPERTIES.xml
+
+Examples:
+  ACCOUNT-PROPERTIES.xml
+  TRANSFER-PROPERTIES.xml
+  MYSERVICE-PROPERTIES.xml
+```
+
+Use ALL-CAPS domain name.
+
+---
+
+## Full Template
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<properties refresh-policy="automatic">
+
+  <!--
+    Group name format: {ApplicationLabel}.{FlowName}
+    ApplicationLabel: set on PropertyReader node, e.g. "BS_MyService"
+    FlowName:         the message flow name, e.g. "GetMyData"
+  -->
+  <group name="BS_MyService.GetMyData">
+
+    <!-- ═══════════════════════════════════════════
+         LOGGING & AUDIT
+         ═══════════════════════════════════════════ -->
+    <group name="Logging">
+      <!-- Enable/disable log (full message body stored) -->
+      <property name="LogEnabled"     value="TRUE" />
+      <!-- Enable/disable audit (key fields + timestamps) -->
+      <property name="AuditEnabled"   value="TRUE" />
+      <!-- Enable/disable field masking in audit -->
+      <property name="MaskingEnabled" value="TRUE" />
+
+      <!-- Up to 10 key-value pairs to extract from message for audit -->
+      <!-- key = human label, value = XPath-style path into message tree -->
+      <property name="key1"   value="CUSTOMER.ID" />
+      <property name="value1" value="*.Body.CustomerId" />
+      <property name="key2"   value="ACCOUNT.NO" />
+      <property name="value2" value="*.Body.AccountNumber" />
+      <!-- key3-key10, value3-value10 as needed -->
+
+      <!-- Fields to mask in INCOMING request audit (multi-value) -->
+      <property name="maskingIn">
+        <value>*.Header.ChannelUserInfo.UserPassword</value>
+        <!-- add more sensitive fields here -->
+      </property>
+      <!-- Fields to mask in OUTGOING response audit (multi-value) -->
+      <property name="maskingOut">
+        <value>*.Header.ChannelUserInfo.UserPassword</value>
+      </property>
+    </group>
+
+    <!-- ═══════════════════════════════════════════
+         RETRY
+         ═══════════════════════════════════════════ -->
+    <group name="Retry">
+      <property name="RetryEnabled"       value="FALSE" />
+      <property name="maxRetryCount"      value="5" />
+      <property name="minWaitDurationSec" value="60" />
+    </group>
+
+    <!-- ═══════════════════════════════════════════
+         INTERNAL SERVICE CHAINING
+         ═══════════════════════════════════════════ -->
+    <group name="Variables">
+      <!-- Offset added to correlation ID for each leg of a chained flow -->
+      <property name="callCorrIDOffset" value="1" />
+    </group>
+
+    <!-- ═══════════════════════════════════════════
+         SCHEMA VALIDATION
+         ═══════════════════════════════════════════ -->
+    <group name="SchemaValidation">
+      <property name="ValidationEnabled" value="FALSE" />
+    </group>
+
+    <!-- ═══════════════════════════════════════════
+         MQ MESSAGE PRIORITY
+         ═══════════════════════════════════════════ -->
+    <group name="Priority">
+      <!-- MQ message priority: 0 (lowest) to 9 (highest). Default: 4 -->
+      <property name="Priority" value="4" />
+    </group>
+
+    <!-- ═══════════════════════════════════════════
+         BACKEND ROUTING
+         ═══════════════════════════════════════════ -->
+    <group name="BankIdForRoutingService">
+      <!--
+        Multi-value property. Each <property> is one route.
+        Values within each property:
+          [1] = backend system ID (e.g. T24, NIWS, ODM)
+          [2] = service/operation name
+          [3] = full URL
+      -->
+      <property name="qiwa">
+        <value>T24</value>
+        <value>GetMyDataService</value>
+        <value>http://backend-host:7800/services/GetMyData</value>
+      </property>
+    </group>
+
+  </group>
+
+  <!-- Add more flow groups here:
+  <group name="BS_MyService.CreateMyData">
+    ...
+  </group>
+  -->
+
+</properties>
+```
+
+---
+
+## Accessing Properties in ESQL
+
+```esql
+-- Pattern: Environment.Properties.{ApplicationLabel}.{FlowName}.{Group}.{Property}
+
+-- Boolean flags
+Environment.Properties.BS_MyService.GetMyData.Logging.AuditEnabled
+Environment.Properties.BS_MyService.GetMyData.Retry.RetryEnabled
+
+-- Numeric
+Environment.Properties.BS_MyService.GetMyData.Retry.maxRetryCount
+Environment.Properties.BS_MyService.GetMyData.Priority.Priority
+
+-- Multi-value (index starts at 1)
+Environment.Properties.BS_MyService.GetMyData.BankIdForRoutingService.qiwa[1]  -- 'T24'
+Environment.Properties.BS_MyService.GetMyData.BankIdForRoutingService.qiwa[2]  -- 'GetMyDataService'
+Environment.Properties.BS_MyService.GetMyData.BankIdForRoutingService.qiwa[3]  -- URL
+```
+
+---
+
+## Required Groups (every flow must have)
+
+| Group | Required Properties |
+|---|---|
+| `Logging` | `LogEnabled`, `AuditEnabled`, `MaskingEnabled`, `maskingIn` (at minimum with UserPassword) |
+| `Retry` | `RetryEnabled` |
+| `SchemaValidation` | `ValidationEnabled` |
+| `Priority` | `Priority` |
+
+`Variables` and `BankIdForRoutingService` only needed if the flow uses service chaining or backend HTTP calls respectively.

package/_agent_reference/config/queue-definition.md

@@ -0,0 +1,141 @@
+# Queue Definition Template
+
+Every MQ-based application needs an MQSC shell script to create its queues. HTTP and File flows do NOT need queue definitions.
+
+---
+
+## File Naming
+
+```
+<Domain>QueuesDefinition.sh
+
+Examples:
+  ACCOUNTQueuesDefinition.sh
+  TRANSFERQueuesDefinition.sh
+  MYSERVICEQueuesDefinition.sh
+```
+
+---
+
+## Queue Naming Convention
+
+```
+<Tier>.<Verb>.<Domain>.<Resource>.<Qualifier>.RQ   ← request queue
+<Tier>.<Verb>.<Domain>.<Resource>.<Qualifier>.RS   ← response queue
+<QUEUE_NAME>.BACKOUT                                ← dead letter queue
+
+Tier:   BS (Business Service) | ESB (Enterprise Service Bus)
+Verb:   GET | SEARCH | CREATE | UPDATE | DELETE | PROCESS
+```
+
+Examples:
+```
+BS.GET.CUSTOMER.ACCOUNT.DETAILS.RQ
+BS.GET.CUSTOMER.ACCOUNT.DETAILS.RS
+BS.GET.CUSTOMER.ACCOUNT.DETAILS.RQ.BACKOUT
+BS.GET.CUSTOMER.ACCOUNT.DETAILS.RS.BACKOUT
+
+ESB.COMMON.UPDATE.CUSTOMER.ACCOUNT.NICKNAME.RQ
+ESB.COMMON.UPDATE.CUSTOMER.ACCOUNT.NICKNAME.RS
+```
+
+---
+
+## Shell Script Template
+
+```bash
+#!/bin/bash
+# Queue definitions for <DOMAIN> service
+# Application: <ApplicationName>
+# Created: <date>
+
+QMGR_NAME="QMGR01"   # replace with actual queue manager name
+
+runmqsc ${QMGR_NAME} << EOF
+
+*---------------------------------------------------------
+* <FlowName> - <Brief Description>
+*---------------------------------------------------------
+
+DEFINE QLOCAL('BS.<VERB>.<RESOURCE>.<QUALIFIER>.RQ.BACKOUT') +
+  DEFPSIST(YES) +
+  MAXDEPTH(640000) +
+  REPLACE
+
+DEFINE QLOCAL('BS.<VERB>.<RESOURCE>.<QUALIFIER>.RQ') +
+  DEFPSIST(YES) +
+  MAXDEPTH(640000) +
+  BOQNAME('BS.<VERB>.<RESOURCE>.<QUALIFIER>.RQ.BACKOUT') +
+  BOTHRESH(5) +
+  REPLACE
+
+DEFINE QLOCAL('BS.<VERB>.<RESOURCE>.<QUALIFIER>.RS.BACKOUT') +
+  DEFPSIST(YES) +
+  MAXDEPTH(640000) +
+  REPLACE
+
+DEFINE QLOCAL('BS.<VERB>.<RESOURCE>.<QUALIFIER>.RS') +
+  DEFPSIST(YES) +
+  MAXDEPTH(640000) +
+  BOQNAME('BS.<VERB>.<RESOURCE>.<QUALIFIER>.RS.BACKOUT') +
+  BOTHRESH(5) +
+  REPLACE
+
+*---------------------------------------------------------
+* Add more queue pairs below for additional flows
+*---------------------------------------------------------
+
+EOF
+
+echo "Queue definitions complete for ${QMGR_NAME}"
+```
+
+---
+
+## Queue Properties Reference
+
+| Property | Value | Meaning |
+|---|---|---|
+| `DEFPSIST(YES)` | YES | Messages survive broker restart |
+| `MAXDEPTH(640000)` | 640,000 | Max messages in queue |
+| `BOQNAME(...)` | Queue name | Backout queue for failed messages |
+| `BOTHRESH(5)` | 5 | Move to backout queue after 5 failed gets |
+| `REPLACE` | — | Overwrite if queue already exists |
+
+---
+
+## DB Script Template
+
+Every new service must also be registered in the routing database.
+
+**File naming**: `<Domain>DBScript.sql`
+
+```sql
+-- ==========================================================
+-- Service registration for <ApplicationName>
+-- ==========================================================
+
+-- Register service operation(s) in routing table
+-- ESBFUNCID: unique 8-char ID, format: <ABBREV><SEQ> e.g. GMYD0001
+INSERT INTO MCR_CHANNESBFUNC_TBL (ESBFUNCID, ESBFUNCNAME, REQUEST_QUEUE_NAME, RESPONSE_QUEUE_NAME)
+VALUES ('XXXX0001', 'GET_MY_DATA', 'BS.GET.MY.DATA.RQ', 'BS.GET.MY.DATA.RS');
+
+-- Grant access to channels that can call this service
+-- Common CHANNID values: MOBILE, WEB, IVR, BATCH, INTERNAL
+INSERT INTO MCR_CHANNAUTH_TBL (CHANNID, ESBFUNCID) VALUES ('MOBILE',   'XXXX0001');
+INSERT INTO MCR_CHANNAUTH_TBL (CHANNID, ESBFUNCID) VALUES ('WEB',      'XXXX0001');
+INSERT INTO MCR_CHANNAUTH_TBL (CHANNID, ESBFUNCID) VALUES ('INTERNAL', 'XXXX0001');
+
+COMMIT;
+```
+
+---
+
+## Checklist
+
+- [ ] One backout queue per primary queue (never skip this)
+- [ ] `DEFPSIST(YES)` on all queues (messages must survive restart)
+- [ ] `BOTHRESH(5)` on all primary queues
+- [ ] Register each operation in `MCR_CHANNESBFUNC_TBL`
+- [ ] Grant channel access in `MCR_CHANNAUTH_TBL` for each allowed channel
+- [ ] `ESBFUNCID` must be unique across all services (check existing DB scripts)

package/_agent_reference/esql-coding-standards.md

@@ -0,0 +1,112 @@
+# ESQL Coding Standards & Syntax (Authoritative)
+
+Load this file before writing, editing, refactoring, or reviewing any `.esql` module.
+
+## ESQL Expertise & Syntax
+- **Core constructs:** DECLARE, SET, IF/ELSEIF/ELSE, CASE, WHILE, FOR, BEGIN/END, ROW, LIST
+- **Variable types:** Standard variables, SHARED variables (cache), EXTERNAL variables (User Defined Properties / UDPs)
+- **Built-in functions:** CAST, SUBSTRING, TRIM, UPPER, LOWER, LENGTH, POSITION, REPLACE, COALESCE, OVERLAY, EVAL, CARDINALITY, FIELDNAME, FIELDTYPE, FIELDVALUE, EXISTS, LASTMOVE, ASBITSTREAM, THE
+- **Message tree domains:** InputRoot, OutputRoot, Environment, LocalEnvironment, InputLocalEnvironment, InputExceptionList
+- **Parser domains:** XMLNSC, JSON, DFDL, MRM, BLOB, MIME, SOAP
+- **Namespace handling:** Strictly enforce DECLARE NAMESPACE for XMLNSC and SOAP domains. Use namespaces correctly in tree navigation
+- **Routing & Propagation:** PROPAGATE TO TERMINAL 'out' / 'out1' / 'out2' / 'failure' / 'alternate'. PROPAGATE TO LABEL
+- **Error handling:** THROW USER EXCEPTION, RESIGNAL, parsing InputExceptionList tree to extract BIP messages
+- **Database access:** ESQL PASSTHRU, SELECT/INSERT/UPDATE/DELETE via ODBC datasources. Handle nulls safely
+- **Module types:** CREATE COMPUTE MODULE, CREATE FILTER MODULE, CREATE DATABASE MODULE, CREATE FUNCTION, CREATE PROCEDURE
+
+## Coding Standards — ESQL (STRICT RULES)
+
+### REFERENCE TO (mandatory)
+Always use REFERENCE TO for repeated access to the same tree path. Never repeat a full path like `InputRoot.XMLNSC.Order.Item` multiple times — declare a reference and use it:
+```esql
+-- WRONG: repeated full tree paths
+SET OutputRoot.XMLNSC.Response.Header.Status = 'OK';
+SET OutputRoot.XMLNSC.Response.Header.Code = '200';
+
+-- CORRECT: use REFERENCE TO
+DECLARE refHeader REFERENCE TO OutputRoot.XMLNSC.Response.Header;
+SET refHeader.Status = 'OK';
+SET refHeader.Code = '200';
+```
+
+### CARDINALITY optimization (mandatory)
+Never call CARDINALITY() inside a WHILE loop condition. Evaluate it once into a declared INTEGER before the loop:
+```esql
+-- WRONG
+WHILE I <= CARDINALITY(InputRoot.XMLNSC.Items.Item[]) DO
+
+-- CORRECT
+DECLARE itemCount INTEGER CARDINALITY(InputRoot.XMLNSC.Items.Item[]);
+WHILE I <= itemCount DO
+```
+
+### Full message copy
+Use `SET OutputRoot = InputRoot;` for full copies — do not copy field by field.
+
+### Memory management
+Use `DELETE FIELD` to remove Environment and LocalEnvironment variables after processing to avoid memory leaks in batch processing.
+
+### Comments
+Comment complex transformations — explain the business intent, not the mechanics.
+
+### Standard boilerplate
+Every Compute module MUST include CopyMessageHeaders() and CopyEntireMessage() procedures:
+```esql
+CREATE PROCEDURE CopyMessageHeaders() BEGIN
+    DECLARE I INTEGER 1;
+    DECLARE headerCount INTEGER CARDINALITY(InputRoot.*[]);
+    WHILE I < headerCount DO
+        SET OutputRoot.*[I] = InputRoot.*[I];
+        SET I = I + 1;
+    END WHILE;
+END;
+
+CREATE PROCEDURE CopyEntireMessage() BEGIN
+    SET OutputRoot = InputRoot;
+END;
+```
+
+## Coding Standards — Database Access (STRICT RULES)
+
+### Stored procedures
+Declare with: `LANGUAGE DATABASE DYNAMIC RESULT SETS 1 EXTERNAL NAME "dbo.<ProcedureName>"`
+Store outputs into `Environment.Variables.<ArrayName>.ResultSet[]`
+
+### SQL injection prevention (CRITICAL)
+PASSTHRU with string concatenation is STRICTLY FORBIDDEN. All dynamic queries MUST use parameterized form with ? placeholders:
+```esql
+-- FORBIDDEN — SQL injection risk
+PASSTHRU('SELECT * FROM users WHERE id = ' || CAST(userId AS CHARACTER));
+
+-- REQUIRED — parameterized query
+PASSTHRU('SELECT * FROM users WHERE id = ?' TO Database.DSN VALUES(userId));
+```
+
+## Coding Standards — Error Handling
+- Do NOT use THROW USER EXCEPTION for business logic validations
+- Set error state via: `SET Environment.Variables.MWResponse.status = '<error_code>';`
+- Use `CALL getEsbChannlsErrorCodeDescriptionFrom(errorCode, language, errorDescription)` for localized error messages
+- Use `CALL Create_esbXML_Response_Header(...)` for standardized XML response headers
+- All error flows MUST route through the framework `LogError` subflow
+- Route validation failures using `PROPAGATE TO TERMINAL 'out2'; RETURN FALSE;`
+
+## Coding Standards — Naming Conventions
+
+| Artifact | Convention | Example |
+|---|---|---|
+| BROKER SCHEMA | com.qiwa.esb.<flow_name_lowercase> | com.qiwa.esb.employeeflow |
+| ESQL module | <FlowName>_<NodeName> | CheckValTransEmployeeFlow_CallDB_GetUser |
+| Node names | UpperCamelCase, descriptive | ValidateRequest, CallEmployeeDB |
+| Subflow names | UpperCamelCase | GetEmployeeData |
+| Application name | UpperCamelCase | EmployeeService |
+| Service name | lowercase, no hyphens | employee |
+| Package path | com/qiwa/esb/<servicename>/ | com/qiwa/esb/employee/ |
+
+## State Management & Properties
+- Use `Environment.Variables` for intermediate state, API responses, database results, transfer types
+- Access via REFERENCE TO: `DECLARE EV REFERENCE TO Environment.Variables;`
+- Load properties from: `Environment.Properties.<ProjectName>.<FlowName>.Variables`
+
+## Documentation
+- Add inline comments for all business logic blocks explaining the business intent
+- Change stamps format: `--- <Reason/Change> --- <Developer Name> <Date> ---`