@llm4ts/shell 2.12.0 → 2.13.1

package/kits/soap-ace/scaffolds/ace12-rest-api/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to __API__
+
+House rules for every change, human or agent. The contract comes first: the
+code implements `contracts/`, never the other way round.
+
+## The contract
+
+- `contracts/openapi-ace.yaml` (OpenAPI 3.0.3, what ACE 12 imports) and
+  `contracts/openapi.yaml` (3.1) are projected from `contracts/api-design.json`.
+  Never edit them; a contract change is a design change upstream.
+- Every property and parameter carries `x-soap-source`: the XSD path it maps
+  from or to. Every enumeration carries `x-soap-enum-map`: SOAP value → REST
+  value. Implement exactly these mappings; `contracts/mapping.json` lists
+  every SOAP field.
+- Errors are RFC 9457 problem details. `x-problem-codes` names, per HTTP
+  status, the problem `code` and the SOAP outcome codes and fault elements it
+  maps from. Anything unmapped is `502 backend-error`.
+
+## Project layout
+
+- `__API__/` is the REST API project. Each resource has its own broker
+  schema folder under `resources/` (`resources/accounts/`,
+  `resources/creditTransfers/`, broker schema `resources.accounts`) holding
+  one subflow per operation (named after its `operationId`) and its ESQL
+  modules.
+- `__API__Lib/` holds the imported WSDL and XSDs, the subflow that calls the
+  backend (`SOAPRequest` node, WS-Security and endpoints from policies), and
+  the error-mapping subflow every operation uses.
+- `__API__Policies/` holds one HTTP/SOAP policy set per environment (`dev`,
+  `test`, `uat`); no endpoint, credential, or certificate path is ever
+  hard-coded in a flow or ESQL module.
+
+## ESQL
+
+- One `CREATE COMPUTE MODULE` per mapping step, named
+  `<operationId>_<Step>` (`listAccounts_BuildRequest`, `listAccounts_MapResponse`).
+- Build SOAP requests and REST responses field by field from the mapping;
+  never copy trees wholesale (`SET OutputRoot.JSON.Data = InputRoot...`),
+  which would leak SOAP names and the esito envelope.
+- Amounts are decimal strings: `CAST(x AS CHARACTER)` of the XSD decimal,
+  never a JSON number. Dates stay ISO 8601 as received.
+- Enumerations go through a `CASE` over `x-soap-enum-map`; an unmapped value
+  is an error routed to the error subflow, never passed through.
+- Absent optional values are omitted; `xsi:nil` becomes JSON `null` only
+  where the contract says `nullable`.
+- See `docs/patterns/` for the recurring cases.
+
+## Tests and gates
+
+- Every operation has ACE unit tests in `__API___Test/src/resources/<resource>/` that
+  run the flow against the recorded backend stubs in `__API___Test/stubs/`
+  (built from `test-data/`): the happy path, every mapped business error,
+  and every enum value the contract lists.
+- `scripts/ace-gates.sh build` packages the BAR with `ibmint`;
+  `scripts/ace-gates.sh test` deploys to a scratch work directory and runs the
+  test project. Both must pass before a story is merged.

package/kits/soap-ace/scaffolds/ace12-rest-api/README.md

@@ -0,0 +1,16 @@
+# __API__
+
+The IBM App Connect Enterprise 12 REST API in front of the `__SERVICE__` SOAP
+service, seeded by `soap-epic` from the approved design and implemented story
+by story by `epic-stories`.
+
+| Path                   | What it holds                                                          | Edited by                  |
+| ---------------------- | ---------------------------------------------------------------------- | -------------------------- |
+| `contracts/`           | the approved design, the OpenAPI contract, the 1:1 mapping, the WSDL   | nobody (regenerated)       |
+| `__API__/`             | the REST API project: descriptors, main flow, one broker schema per resource under `resources/` | stories                    |
+| `__API__Lib/`          | shared library: the imported WSDL, SOAP call and error-mapping subflows | the `shared-lib` story     |
+| `__API__Policies/`     | policy project: backend endpoints and security per environment          | the `policies` story       |
+| `__API___Test/`        | ACE unit tests (JUnit) with the recorded backend stubs                  | stories                    |
+| `test-data/`           | masked SOAP exchanges recorded by `soap-sample`, the stubs' source      | nobody (regenerated)       |
+| `docs/`                | analysis reports and ESQL pattern cards                                 | nobody (regenerated)       |
+| `scripts/ace-gates.sh` | the gates `epic-stories` runs: `build` and `test`                       | the team                   |

package/kits/soap-ace/scaffolds/ace12-rest-api/scripts/ace-gates-container.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# The same gates inside the ACE container image, for machines without a local
+# ACE install:  ace-gates-container.sh build | test
+# ACE_IMAGE names the image your organisation uses (entitled registries need a login).
+set -euo pipefail
+image="${ACE_IMAGE:?set ACE_IMAGE to your ACE 12 image}"
+exec docker run --rm -e LICENSE=accept -e MQSI_PROFILE=/opt/ibm/ace-12/server/bin/mqsiprofile \
+  -v "$PWD":/work -w /work --entrypoint bash "$image" scripts/ace-gates.sh "${1:-build}"

package/kits/soap-ace/scaffolds/ace12-rest-api/scripts/ace-gates.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# ACE 12 gates for llm4ts epic-stories:  ace-gates.sh build | test
+#
+# Runs on a developer laptop with ACE 12 installed. The environment comes from
+# mqsiprofile: MQSI_PROFILE names it, or ACE_HOME (default /opt/ibm/ace-12)
+# locates it. Command lines follow ACE 12.0.7+ (ibmint package/deploy and
+# IntegrationServer --test-project); check them against your fix pack and
+# override the whole gate with LLM4TS_GATES if they differ.
+set -euo pipefail
+
+API="__API__"
+PROFILE="${MQSI_PROFILE:-${ACE_HOME:-/opt/ibm/ace-12}/server/bin/mqsiprofile}"
+if [ ! -f "$PROFILE" ]; then
+  echo "ace-gates: mqsiprofile not found at $PROFILE (set MQSI_PROFILE or ACE_HOME)" >&2
+  exit 2
+fi
+set +u
+# shellcheck disable=SC1090
+. "$PROFILE" >/dev/null
+set -u
+
+command="${1:-build}"
+mkdir -p build
+case "$command" in
+  build)
+    ibmint package --input-path . --output-bar-file "build/${API}.bar" \
+      --project "$API" --project "${API}Lib" --project "${API}Policies"
+    ;;
+  test)
+    work="build/test-work"
+    rm -rf "$work"
+    mqsicreateworkdir "$work" >/dev/null
+    ibmint deploy --input-path . --output-work-directory "$work" \
+      --project "$API" --project "${API}Lib" --project "${API}Policies" --project "${API}_Test"
+    IntegrationServer --work-dir "$work" --test-project "${API}_Test" --start-msgflows false
+    ;;
+  *)
+    echo "usage: ace-gates.sh build | test" >&2
+    exit 64
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.12.0",
+  "version": "2.13.1",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/platform-node-shared": "4.0.0-rc.115",
-    "@llm4ts/core": "2.12.0",
-    "@llm4ts/flow": "2.12.0",
-    "@llm4ts/runner": "2.12.0"
+    "@llm4ts/core": "2.13.1",
+    "@llm4ts/runner": "2.13.1",
+    "@llm4ts/flow": "2.13.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"