orbit-code-ai 0.1.0

package/_agent_reference/templates/http-flow.md

@@ -0,0 +1,185 @@
+# Template: HTTP/REST Flow
+
+Use this template when building a flow exposed as a REST endpoint that calls a backend service and returns a JSON response synchronously.
+
+---
+
+## Files to Create
+
+```
+MyServiceApp/
+├── .project
+├── GetMyData.msgflow
+├── GetMyData_Compute.esql
+├── GetMyData_PrepareRequest.esql
+├── GetMyData_MapResponse.esql
+└── GetMyData.json                 ← REST API descriptor (optional, for swagger)
+```
+
+---
+
+## Message Flow Structure (GetMyData.msgflow)
+
+```
+[Rest_Input_Node]       ← HTTP input, parses JSON to XMLNSC
+      ↓ out
+[PropertyReader]        ← ApplicationLabel="BS_MyService", PropertiesFileName="MYSERVICE-PROPERTIES.xml"
+      ↓ out
+[LogAudit]              ← flowStart=TRUE
+      ↓ out
+[GetMyData_Compute]     ← validate input, set routing
+      ↓ out
+[HTTPRequestAdapter]    ← call backend (set IsT24Adapter=TRUE or relevant flag)
+      ↓ out
+[HTTPResponseAdapter]   ← normalize backend response
+      ↓ out
+[GetMyData_MapResponse] ← map to ESB response structure
+      ↓ out
+[LogOutgoingAudit]      ← flowStart=FALSE
+      ↓ out
+[HTTP Reply Node]       ← return JSON response to caller
+
+All failure terminals → [ErrorHandler] → [LogError] → [MWBusinessErrorResponse]
+```
+
+Note: HTTP flows use `MWBusinessErrorResponse` (not `MQ_Dead_Output_Node`) on the error path.
+
+---
+
+## GetMyData_Compute.esql
+
+```esql
+BROKER SCHEMA Qiwa.BS_MyService
+
+CREATE COMPUTE MODULE GetMyData_Compute
+    CREATE FUNCTION Main() RETURNS BOOLEAN
+    BEGIN
+        CALL CopyMessageHeaders();
+        CALL CopyEntireMessage();
+
+        -- JSON input arrives as XMLNSC (Rest_Input_Node converts it)
+        DECLARE customerId CHARACTER InputRoot.XMLNSC.Root.Body.CustomerId;
+
+        -- Validate
+        IF customerId IS NULL OR customerId = '' THEN
+            SET Environment.ErrorDetails.Code = '99999999';
+            SET Environment.ErrorDetails.EnglishMsg = 'CustomerId is required';
+            RETURN FALSE;
+        END IF;
+
+        -- Generate correlation ID
+        DECLARE corrId CHARACTER;
+        CALL getChannelCorrelationID(
+            InputRoot.XMLNSC.Root.Header.ChannelId,
+            InputRoot.XMLNSC.Root.Header.SessionId,
+            corrId
+        );
+        SET OutputRoot.HTTPInputHeader.X-Correlation-Id = corrId;
+
+        RETURN TRUE;
+    END;
+END MODULE;
+```
+
+---
+
+## GetMyData_PrepareRequest.esql
+
+```esql
+BROKER SCHEMA Qiwa.BS_MyService
+
+CREATE COMPUTE MODULE GetMyData_PrepareRequest
+    CREATE FUNCTION Main() RETURNS BOOLEAN
+    BEGIN
+        CALL CopyMessageHeaders();
+
+        -- Set target URL from properties
+        SET Environment.Destination.HTTP.RequestURL =
+            Environment.Properties.BS_MyService.GetMyData.BankIdForRoutingService.qiwa[3];
+
+        -- Build backend request payload
+        SET OutputRoot.XMLNSC.BackendRequest.CustomerId =
+            InputRoot.XMLNSC.Root.Body.CustomerId;
+
+        RETURN TRUE;
+    END;
+END MODULE;
+```
+
+---
+
+## GetMyData_MapResponse.esql
+
+```esql
+BROKER SCHEMA Qiwa.BS_MyService
+
+CREATE COMPUTE MODULE GetMyData_MapResponse
+    CREATE FUNCTION Main() RETURNS BOOLEAN
+    BEGIN
+        CALL CopyMessageHeaders();
+
+        -- Build standard ESB response
+        SET OutputRoot.XMLNSC.Root.Header.ResponseStatus.Code       = '00000000';
+        SET OutputRoot.XMLNSC.Root.Header.ResponseStatus.Status     = 'Success';
+        SET OutputRoot.XMLNSC.Root.Header.ResponseStatus.EnglishMsg = 'Success';
+
+        -- Map business data from backend response
+        SET OutputRoot.XMLNSC.Root.Body.AccountBalance =
+            InputRoot.XMLNSC.BackendResponse.Balance;
+
+        -- Set HTTP response code
+        SET OutputRoot.HTTPResponseHeader."$statusCode" = 200;
+
+        RETURN TRUE;
+    END;
+END MODULE;
+```
+
+---
+
+## MYSERVICE-PROPERTIES.xml (HTTP variant)
+
+Same structure as MQ flow — see `templates/mq-flow.md` for full XML.
+
+Key difference for HTTP flows — `Retry` is usually disabled:
+```xml
+<group name="Retry">
+  <property name="RetryEnabled" value="FALSE" />
+</group>
+```
+
+---
+
+## Error Response (MWBusinessErrorResponse)
+
+On any failure, the error handler returns:
+```json
+{
+  "Root": {
+    "Header": {
+      "ResponseStatus": {
+        "Code": "99999999",
+        "Status": "Error",
+        "EnglishMsg": "Technical error occurred"
+      }
+    }
+  }
+}
+```
+
+HTTP status code: `200` (ESB pattern — errors are in the payload, not HTTP status)
+
+---
+
+## Checklist for New HTTP Flow
+
+- [ ] Create `.msgflow` with `Rest_Input_Node` as entry point
+- [ ] Create Compute, PrepareRequest, MapResponse ESQL modules
+- [ ] Add properties group to properties XML file
+- [ ] Wire ALL failure terminals to `ErrorHandler` → `MWBusinessErrorResponse`
+- [ ] Set `ApplicationLabel` and `PropertiesFileName` on `PropertyReader` node
+- [ ] Set correct backend adapter flag on `HTTPRequestAdapter` node
+- [ ] Set `HTTP Reply Node` as the success terminal exit
+- [ ] Set `OutputRoot.HTTPResponseHeader."$statusCode"` = 200 in MapResponse
+- [ ] Confirm `UserPassword` is masked in audit config
+- [ ] No queue definitions needed for HTTP flows (no MQ infrastructure)

package/_agent_reference/templates/mq-flow.md

@@ -0,0 +1,248 @@
+# Template: MQ Request/Response Flow
+
+Use this template when building a new asynchronous MQ-based message flow.
+
+---
+
+## Files to Create
+
+For a new application called `BS_MyService` with flow `GetMyData`:
+
+```
+MyServiceApp/
+├── .project
+├── GetMyData.msgflow              ← main message flow
+├── GetMyData_Compute.esql         ← your business logic
+├── GetMyData_PrepareRequest.esql  ← format backend request
+├── GetMyData_MapResponse.esql     ← map backend response to ESB format
+└── (referenced shared lib: Framework)
+```
+
+Plus in the Framework (or a domain-specific properties file):
+```
+MYSERVICE-PROPERTIES.xml
+MyServiceQueuesDefinition.sh
+MyServiceDBScript.sql
+```
+
+---
+
+## Message Flow Structure (GetMyData.msgflow)
+
+```
+[MQ_Input_Node]
+      ↓ out
+[PropertyReader]         ← ApplicationLabel="BS_MyService", PropertiesFileName="MYSERVICE-PROPERTIES.xml"
+      ↓ out
+[LogAudit]               ← flowStart=TRUE
+      ↓ out
+[GetMyData_Compute]      ← your ESQL: validate input, prepare backend call
+      ↓ out
+[HTTPRequestAdapter]     ← set IsT24Adapter=TRUE (or relevant backend flag)
+      ↓ out
+[HTTPResponseAdapter]    
+      ↓ out
+[GetMyData_MapResponse]  ← your ESQL: map backend response to Root.Header + Root.Body
+      ↓ out
+[LogOutgoingAudit]       ← flowStart=FALSE
+      ↓ out
+[MQ_Output_Node]         ← or MQ_ReplyToQ_Node for sync reply
+
+All failure terminals → [ErrorHandler] → [LogError] → [MQ_Dead_Output_Node]
+```
+
+---
+
+## GetMyData_Compute.esql
+
+```esql
+BROKER SCHEMA Qiwa.BS_MyService
+
+CREATE COMPUTE MODULE GetMyData_Compute
+    CREATE FUNCTION Main() RETURNS BOOLEAN
+    BEGIN
+        CALL CopyMessageHeaders();
+        CALL CopyEntireMessage();
+
+        -- Validate required input fields
+        DECLARE customerId CHARACTER InputRoot.XMLNSC.Root.Body.CustomerId;
+        IF customerId IS NULL OR customerId = '' THEN
+            SET Environment.ErrorDetails.Code = '99999999';
+            SET Environment.ErrorDetails.EnglishMsg = 'CustomerId is required';
+            RETURN FALSE;  -- routes to failure terminal → ErrorHandler
+        END IF;
+
+        -- Set correlation ID
+        DECLARE corrId CHARACTER;
+        CALL getChannelCorrelationID(
+            InputRoot.XMLNSC.Root.Header.ChannelId,
+            InputRoot.XMLNSC.Root.Header.SessionId,
+            corrId
+        );
+        SET OutputRoot.MQMD.CorrelId = CAST(corrId AS BLOB CCSID 1208);
+
+        RETURN TRUE;
+    END;
+END MODULE;
+```
+
+---
+
+## GetMyData_PrepareRequest.esql
+
+```esql
+BROKER SCHEMA Qiwa.BS_MyService
+
+CREATE COMPUTE MODULE GetMyData_PrepareRequest
+    CREATE FUNCTION Main() RETURNS BOOLEAN
+    BEGIN
+        CALL CopyMessageHeaders();
+
+        -- Build backend request (adjust structure for your backend)
+        SET OutputRoot.XMLNSC.BackendRequest.CustomerId =
+            InputRoot.XMLNSC.Root.Body.CustomerId;
+        SET OutputRoot.XMLNSC.BackendRequest.RequestTime =
+            InputRoot.XMLNSC.Root.Header.RequestTime;
+
+        -- Set HTTP destination from properties
+        SET Environment.Destination.HTTP.RequestURL =
+            Environment.Properties.BS_MyService.GetMyData.BankIdForRoutingService.qiwa[3];
+
+        RETURN TRUE;
+    END;
+END MODULE;
+```
+
+---
+
+## GetMyData_MapResponse.esql
+
+```esql
+BROKER SCHEMA Qiwa.BS_MyService
+
+CREATE COMPUTE MODULE GetMyData_MapResponse
+    CREATE FUNCTION Main() RETURNS BOOLEAN
+    BEGIN
+        CALL CopyMessageHeaders();
+        CALL CopyEntireMessage();
+
+        -- Map backend response to ESB standard structure
+        SET OutputRoot.XMLNSC.Root.Header.ResponseStatus.Code   = '00000000';
+        SET OutputRoot.XMLNSC.Root.Header.ResponseStatus.Status = 'Success';
+        SET OutputRoot.XMLNSC.Root.Header.ResponseStatus.EnglishMsg = 'Success';
+
+        -- Map business data
+        SET OutputRoot.XMLNSC.Root.Body.AccountBalance =
+            InputRoot.XMLNSC.BackendResponse.Balance;
+        -- ... map other fields
+
+        RETURN TRUE;
+    END;
+END MODULE;
+```
+
+---
+
+## MYSERVICE-PROPERTIES.xml
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<properties refresh-policy="automatic">
+
+  <group name="BS_MyService.GetMyData">
+
+    <group name="Logging">
+      <property name="LogEnabled"     value="TRUE" />
+      <property name="AuditEnabled"   value="TRUE" />
+      <property name="MaskingEnabled" value="TRUE" />
+      <property name="key1"   value="CUSTOMER.ID" />
+      <property name="value1" value="*.Body.CustomerId" />
+      <property name="maskingIn">
+        <value>*.Header.ChannelUserInfo.UserPassword</value>
+      </property>
+      <property name="maskingOut">
+        <value>*.Header.ChannelUserInfo.UserPassword</value>
+      </property>
+    </group>
+
+    <group name="Retry">
+      <property name="RetryEnabled"       value="FALSE" />
+      <property name="maxRetryCount"      value="5" />
+      <property name="minWaitDurationSec" value="60" />
+    </group>
+
+    <group name="Variables">
+      <property name="callCorrIDOffset" value="1" />
+    </group>
+
+    <group name="SchemaValidation">
+      <property name="ValidationEnabled" value="FALSE" />
+    </group>
+
+    <group name="Priority">
+      <property name="Priority" value="4" />
+    </group>
+
+    <group name="BankIdForRoutingService">
+      <property name="qiwa">
+        <value>T24</value>
+        <value>GetMyDataService</value>
+        <value>http://backend-host:port/services/GetMyData</value>
+      </property>
+    </group>
+
+  </group>
+
+</properties>
+```
+
+---
+
+## MyServiceQueuesDefinition.sh
+
+```bash
+#!/bin/bash
+# Queue definitions for BS_MyService
+
+runmqsc QMGR_NAME << EOF
+
+DEFINE QLOCAL('BS.GET.MY.DATA.RQ.BACKOUT') DEFPSIST(YES) MAXDEPTH(640000) REPLACE
+DEFINE QLOCAL('BS.GET.MY.DATA.RQ') DEFPSIST(YES) MAXDEPTH(640000) BOQNAME('BS.GET.MY.DATA.RQ.BACKOUT') BOTHRESH(5) REPLACE
+
+DEFINE QLOCAL('BS.GET.MY.DATA.RS.BACKOUT') DEFPSIST(YES) MAXDEPTH(640000) REPLACE
+DEFINE QLOCAL('BS.GET.MY.DATA.RS') DEFPSIST(YES) MAXDEPTH(640000) BOQNAME('BS.GET.MY.DATA.RS.BACKOUT') BOTHRESH(5) REPLACE
+
+EOF
+```
+
+---
+
+## MyServiceDBScript.sql
+
+```sql
+-- Register the service in routing table
+INSERT INTO MCR_CHANNESBFUNC_TBL (ESBFUNCID, ESBFUNCNAME, REQUEST_QUEUE_NAME, RESPONSE_QUEUE_NAME)
+VALUES ('GMYD0001', 'GET_MY_DATA', 'BS.GET.MY.DATA.RQ', 'BS.GET.MY.DATA.RS');
+
+-- Grant channel access
+INSERT INTO MCR_CHANNAUTH_TBL (CHANNID, ESBFUNCID)
+VALUES ('MOBILE', 'GMYD0001');
+VALUES ('WEB', 'GMYD0001');
+```
+
+---
+
+## Checklist for New MQ Flow
+
+- [ ] Create application project folder
+- [ ] Create `.msgflow` file with all nodes wired
+- [ ] Create `_Compute.esql` for input validation and routing
+- [ ] Create `_PrepareRequest.esql` for backend request formatting
+- [ ] Create `_MapResponse.esql` for response normalization
+- [ ] Add properties group to `MYSERVICE-PROPERTIES.xml` (or create new file)
+- [ ] Create queue definition shell script
+- [ ] Create DB script to register service and channel auth
+- [ ] Wire ALL failure terminals to `ErrorHandler`
+- [ ] Set `ApplicationLabel` and `PropertiesFileName` on `PropertyReader` node
+- [ ] Set correct backend adapter flag on `HTTPRequestAdapter` node
+- [ ] Confirm `UserPassword` is in `maskingIn` and `maskingOut`

package/bin/import-specifier.mjs

@@ -0,0 +1,13 @@
+import { join, win32 } from 'path'
+import { pathToFileURL } from 'url'
+
+export function getDistImportSpecifier(baseDir) {
+  if (/^[A-Za-z]:\\/.test(baseDir)) {
+    const distPath = win32.join(baseDir, '..', 'dist', 'cli.mjs')
+    return `file:///${distPath.replace(/\\/g, '/')}`
+  }
+
+  const joinImpl = join
+  const distPath = joinImpl(baseDir, '..', 'dist', 'cli.mjs')
+  return pathToFileURL(distPath).href
+}

package/bin/import-specifier.test.mjs

@@ -0,0 +1,13 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { getDistImportSpecifier } from './import-specifier.mjs'
+
+test('builds a file URL import specifier for dist/cli.mjs', () => {
+  const specifier = getDistImportSpecifier('C:\\repo\\bin')
+
+  assert.equal(
+    specifier,
+    'file:///C:/repo/dist/cli.mjs',
+  )
+})

package/bin/orbit

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * Orbit AI — AI-powered IBM ACE coding companion
+ *
+ * If dist/cli.mjs exists (built), run that.
+ * Otherwise, tell the user to build first or use `bun run dev`.
+ */
+
+import { existsSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath, pathToFileURL } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const distPath = join(__dirname, '..', 'dist', 'cli.mjs')
+
+if (existsSync(distPath)) {
+  await import(pathToFileURL(distPath).href)
+} else {
+  console.error(`
+  orbitcode: dist/cli.mjs not found.
+
+  Build first:
+    bun run build
+
+  Or run directly with Bun:
+    bun run dev
+
+  See README.md for setup instructions.
+`)
+  process.exit(1)
+}