@cxtms/cx-schema 1.7.4 → 1.7.6

package/.claude/skills/cx-core/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cx-core
 description: >
-  Provides shared CargoXplorer entity field reference — domain entities, field names, enums, and customValues patterns.
+  Provides shared CXTMS entity field reference — domain entities, field names, enums, and customValues patterns.
   Use when the user asks about CX entity fields, enums, customValues, entity relationships, or needs domain reference for Orders, Contacts, Commodities, Jobs, etc.
 argument-hint: <entity name or question about fields>
 ---

package/.claude/skills/cx-module/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cx-module
 description: >
-  Generates schema-valid CargoXplorer app module YAML files (UI screens, forms, grids, routes).
+  Works with CXTMS app module YAML files — creates, modifies, fixes, validates, and deploys UI screens, forms, grids, and routes.
   Use when the user asks to create, modify, or fix a module YAML file, references *-module.yaml files, or asks about UI components/forms/grids/routes in a CX project.
   Not for workflow YAML files, TypeScript code, or non-YAML tasks.
 argument-hint: <description of what to build>

package/.claude/skills/cx-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cx-workflow
 description: >
-  Generates schema-valid CargoXplorer workflow YAML files (standard process and Flow state machine workflows).
+  Works with CXTMS workflow YAML files — creates, modifies, fixes, validates, and deploys standard process and Flow state machine workflows.
   Use when the user asks to create, modify, or fix a workflow YAML file, references workflow/*.yaml files, or asks about workflow tasks/triggers/activities in a CX project.
   Not for module YAML files, TypeScript code, or non-YAML tasks.
 argument-hint: <description of what to build>
@@ -191,7 +191,8 @@ events:                                     # Workflow-level event handlers
 
 ## Variable References (quick summary)
 
-For full reference: `!cat .claude/skills/cx-workflow/ref-expressions.md`
+For template expressions and value directives: see [ref-expressions-template.md](.claude/skills/cx-workflow/ref-expressions-template.md)
+For NCalc conditions and functions: see [ref-expressions-ncalc.md](.claude/skills/cx-workflow/ref-expressions-ncalc.md)
 
 **`{{ path }}`** — in step inputs. Single `{{ }}` returns raw object. Multiple returns string interpolation.
 **`[variable]`** — in conditions and `expression:` directives. NCalc syntax.
@@ -294,7 +295,8 @@ Implicit variable: `iteration` (zero-based).
 
 | Reference | Load |
 |-----------|------|
-| Expressions & Functions | `!cat .claude/skills/cx-workflow/ref-expressions.md` |
+| Template Expressions & Value Directives | `!cat .claude/skills/cx-workflow/ref-expressions-template.md` |
+| NCalc Expressions & Functions | `!cat .claude/skills/cx-workflow/ref-expressions-ncalc.md` |
 | Flow Workflows (state machines) | `!cat .claude/skills/cx-workflow/ref-flow.md` |
 
 ## Dynamic Schema Access (load on demand)

package/.claude/skills/cx-workflow/{ref-expressions.md → ref-expressions-ncalc.md}

@@ -1,131 +1,16 @@
-# Variable References & Expressions
+# NCalc Expressions & Functions
 
 ## Contents
-- Template Expressions: `{{ path }}` (in step inputs)
-- NCalc Expressions: `[variable]` (in conditions and expression directives)
-- Property Path Syntax (in collection, mapping, variable paths)
+- NCalc expression syntax `[variable]` (in conditions and expression directives)
+- Operators (comparison, logical, arithmetic, ternary, membership)
+- Iterator variables (`[each.*]` and `[item.*]`)
+- Collection functions (any, all, count, sum, first, last, distinct, groupBy, join, etc.)
+- String functions (isNullOrEmpty, length, lower, upper, replace, format, base64, etc.)
+- Date functions (now, parseDate, addDays, formatDate, dateFromUnix, etc.)
+- Math functions (Abs, Ceiling, Floor, Round, Min, Max, etc.)
+- Domain functions (convertWeight, convertDimension)
 
-There are **two distinct syntaxes** for referencing variables, used in different contexts.
-
-## Template Expressions: `{{ path }}` (in step inputs)
-
-Used in step `inputs` values. Resolves variable paths from scoped variables.
-
-```yaml
-inputs:
-  orderId: "{{ inputs.orderId }}"                    # Simple reference
-  url: "{{ chopinConfig.baseUrl }}/api/v1"           # String interpolation
-  order: "{{ Data.GetOrder.order }}"                 # Raw object (single {{ }})
-  name: "Order {{ Data.GetOrder.order.orderNumber }}" # String interpolation (multiple)
-```
-
-**Key behavior**: A single `{{ path }}` returns the **raw object** (preserving type). Multiple `{{ }}` in a string returns string interpolation (each resolved value is `.ToString()`).
-
-### Type Converters (prefix in {{ }})
-
-```yaml
-organizationId: "{{ int organizationId }}"
-amount: "{{ decimal totalAmount }}"
-isActive: "{{ bool isActive }}"
-flag: "{{ boolOrFalse someFlag }}"        # null -> false
-flagOn: "{{ boolOrTrue someFlag }}"       # null -> true
-notes: "{{ emptyIfNull notes }}"          # null -> ""
-notes: "{{ nullIfEmpty notes }}"          # "" or whitespace -> null
-config: "{{ fromJson configJsonString }}" # JSON string -> dict/array
-payload: "{{ toJson someObject }}"        # object -> JSON string
-name: "{{ trim value }}"
-search: "{{ luceneString query }}"        # escape & quote for Lucene
-```
-
-| Converter | Returns | Null handling |
-|-----------|---------|---------------|
-| `string` | `string` | null. Reads `Stream` to string if value is Stream |
-| `int` | `int` | Throws on null |
-| `decimal` | `decimal` | Throws on null |
-| `bool` | `bool` | Throws on null |
-| `boolOrFalse` | `bool` | `false` if null |
-| `boolOrTrue` | `bool` | `true` if null |
-| `datetime` | `DateTime` | Throws on null |
-| `emptyIfNull` | same type | `""` if null, `0` for int?, `0m` for decimal? |
-| `nullIfEmpty` | same type | `null` if empty/whitespace string or empty collection |
-| `luceneString` | `string` | null |
-| `transliterate` | `string` | null (Unicode -> ASCII via Unidecode) |
-| `transliterateUa` | `string` | null (Ukrainian-specific rules) |
-| `fromJson` | `dict` or `array` | null. Empty string -> empty dict |
-| `toJson` | `string` | `""` if null |
-| `trim` | `string` | null |
-
-### Value Directives (in YAML input mappings)
-
-**`expression`** -- Evaluate NCalc expression as a value:
-```yaml
-amount:
-  expression: "[price] * [quantity]"
-```
-
-**`coalesce`** -- First non-null value from a list:
-```yaml
-displayName:
-  coalesce:
-    - "{{ customer.name? }}"
-    - "{{ customer.email? }}"
-    - "Unknown"
-```
-
-**`foreach`** (value context) -- Transform collections inline:
-```yaml
-commodities:
-  foreach: "sourceCommodities"
-  item: "item"                             # default: "item"
-  conditions: "[item.isActive] = true"     # optional NCalc filter per item
-  continueOnError: false                   # optional, skip errors
-  mapping:                                 # dict -> List<dict>, string -> List<object>
-    name: "{{ item.name }}"
-    quantity: "{{ item.qty }}"
-```
-
-**`switch`** (value context) -- Value-based switch (case-insensitive match):
-```yaml
-perLb:
-  switch: "{{ contact.commissionTier }}"
-  cases:
-    "tier1": "{{ rate.customValues.commission_per_lb_tier1 }}"
-    "tier2": "{{ rate.customValues.commission_per_lb_tier2 }}"
-  default: "0"
-```
-
-**`extends`** -- Extend/merge an existing object or array:
-```yaml
-orderData:
-  extends: "{{ existingOrder }}"           # base object or array
-  defaultIfNull: {}                        # fallback if extends is null
-  mapping:                                 # dict: merge overrides. array: append items
-    status: "Updated"
-    notes: "{{ newNotes }}"
-```
-
-**`$raw`** -- Prevent template parsing (pass as-is):
-```yaml
-template:
-  $raw: "This {{ won't }} be parsed"
-```
-
-**`$eval`** -- Parse JSON string then evaluate as template:
-```yaml
-dynamicConfig:
-  $eval: "{{ configJsonString }}"
-```
-
-**`decrypt`** / **`encrypt`** -- AES-CBC encryption (optional key/IV, has defaults):
-```yaml
-apiKey:
-  decrypt:
-    encryptedValue: "{{ encryptedApiKey }}"
-    key: "{{ encryptionKey }}"             # optional Base64 AES key
-    initializationVector: "{{ iv }}"       # optional Base64 IV
-```
-
----
+For template expressions `{{ path }}` used in step inputs, see [ref-expressions-template.md](ref-expressions-template.md).
 
 ## NCalc Expressions: `[variable]` (in conditions and expression directives)
 
@@ -224,24 +109,3 @@ Custom: `ceiling([value])` -- same as `Ceiling` but handles type conversion to d
 |----------|-------------|
 | `convertWeight([weight], 'Kg', 'Lb')` | Weight unit conversion. Returns `decimal` rounded to 5 places |
 | `convertDimension([length], 'Cm', 'In')` | Dimension unit conversion. Returns `decimal` rounded to 3 places |
-
----
-
-## Property Path Syntax (in collection, mapping, variable paths)
-
-Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
-
-| Pattern | Description | Example |
-|---------|-------------|---------|
-| `a.b.c` | Dot-separated nested path | `order.customer.name` |
-| `prop?` | Optional access (null if missing) | `order.customer?.name?` |
-| `list[0]` | Array index | `items[0]` |
-| `list[^1]` | Index from end (last item) | `items[^1]` |
-| `list[*]` | Flatten/wildcard (all items) | `containers[*].commodities` |
-| `list[**]` | Recursive flatten (all depths) | `containerCommodities[**]` |
-| `list[-1]` | Depth filter (leaves only) | `tree[**][-1]` |
-| `list[condition]` | Filter by condition | `items[status=Active]` |
-| `dict['key']` | Dictionary key access | `customValues['myField']` |
-| `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
-| `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |
-| `list[*].{alias:_.parent}` | Field selector referencing parent | `items[*].{parentId:_.orderId}` |

package/.claude/skills/cx-workflow/ref-expressions-template.md

@@ -0,0 +1,148 @@
+# Template Expressions & Value Directives
+
+## Contents
+- Template expression syntax `{{ path }}` (in step inputs)
+- Type converters (int, decimal, bool, fromJson, toJson, etc.)
+- Value directives (expression, coalesce, foreach, switch, extends, $raw, $eval, encrypt/decrypt)
+- Property path syntax (dot paths, array indexing, wildcards, filters, projections)
+
+There are **two distinct syntaxes** for referencing variables, used in different contexts. This file covers **template expressions** used in step inputs. For NCalc conditions and functions, see [ref-expressions-ncalc.md](ref-expressions-ncalc.md).
+
+## Template Expressions: `{{ path }}` (in step inputs)
+
+Used in step `inputs` values. Resolves variable paths from scoped variables.
+
+```yaml
+inputs:
+  orderId: "{{ inputs.orderId }}"                    # Simple reference
+  url: "{{ chopinConfig.baseUrl }}/api/v1"           # String interpolation
+  order: "{{ Data.GetOrder.order }}"                 # Raw object (single {{ }})
+  name: "Order {{ Data.GetOrder.order.orderNumber }}" # String interpolation (multiple)
+```
+
+**Key behavior**: A single `{{ path }}` returns the **raw object** (preserving type). Multiple `{{ }}` in a string returns string interpolation (each resolved value is `.ToString()`).
+
+### Type Converters (prefix in {{ }})
+
+```yaml
+organizationId: "{{ int organizationId }}"
+amount: "{{ decimal totalAmount }}"
+isActive: "{{ bool isActive }}"
+flag: "{{ boolOrFalse someFlag }}"        # null -> false
+flagOn: "{{ boolOrTrue someFlag }}"       # null -> true
+notes: "{{ emptyIfNull notes }}"          # null -> ""
+notes: "{{ nullIfEmpty notes }}"          # "" or whitespace -> null
+config: "{{ fromJson configJsonString }}" # JSON string -> dict/array
+payload: "{{ toJson someObject }}"        # object -> JSON string
+name: "{{ trim value }}"
+search: "{{ luceneString query }}"        # escape & quote for Lucene
+```
+
+| Converter | Returns | Null handling |
+|-----------|---------|---------------|
+| `string` | `string` | null. Reads `Stream` to string if value is Stream |
+| `int` | `int` | Throws on null |
+| `decimal` | `decimal` | Throws on null |
+| `bool` | `bool` | Throws on null |
+| `boolOrFalse` | `bool` | `false` if null |
+| `boolOrTrue` | `bool` | `true` if null |
+| `datetime` | `DateTime` | Throws on null |
+| `emptyIfNull` | same type | `""` if null, `0` for int?, `0m` for decimal? |
+| `nullIfEmpty` | same type | `null` if empty/whitespace string or empty collection |
+| `luceneString` | `string` | null |
+| `transliterate` | `string` | null (Unicode -> ASCII via Unidecode) |
+| `transliterateUa` | `string` | null (Ukrainian-specific rules) |
+| `fromJson` | `dict` or `array` | null. Empty string -> empty dict |
+| `toJson` | `string` | `""` if null |
+| `trim` | `string` | null |
+
+### Value Directives (in YAML input mappings)
+
+**`expression`** -- Evaluate NCalc expression as a value:
+```yaml
+amount:
+  expression: "[price] * [quantity]"
+```
+
+**`coalesce`** -- First non-null value from a list:
+```yaml
+displayName:
+  coalesce:
+    - "{{ customer.name? }}"
+    - "{{ customer.email? }}"
+    - "Unknown"
+```
+
+**`foreach`** (value context) -- Transform collections inline:
+```yaml
+commodities:
+  foreach: "sourceCommodities"
+  item: "item"                             # default: "item"
+  conditions: "[item.isActive] = true"     # optional NCalc filter per item
+  continueOnError: false                   # optional, skip errors
+  mapping:                                 # dict -> List<dict>, string -> List<object>
+    name: "{{ item.name }}"
+    quantity: "{{ item.qty }}"
+```
+
+**`switch`** (value context) -- Value-based switch (case-insensitive match):
+```yaml
+perLb:
+  switch: "{{ contact.commissionTier }}"
+  cases:
+    "tier1": "{{ rate.customValues.commission_per_lb_tier1 }}"
+    "tier2": "{{ rate.customValues.commission_per_lb_tier2 }}"
+  default: "0"
+```
+
+**`extends`** -- Extend/merge an existing object or array:
+```yaml
+orderData:
+  extends: "{{ existingOrder }}"           # base object or array
+  defaultIfNull: {}                        # fallback if extends is null
+  mapping:                                 # dict: merge overrides. array: append items
+    status: "Updated"
+    notes: "{{ newNotes }}"
+```
+
+**`$raw`** -- Prevent template parsing (pass as-is):
+```yaml
+template:
+  $raw: "This {{ won't }} be parsed"
+```
+
+**`$eval`** -- Parse JSON string then evaluate as template:
+```yaml
+dynamicConfig:
+  $eval: "{{ configJsonString }}"
+```
+
+**`decrypt`** / **`encrypt`** -- AES-CBC encryption (optional key/IV, has defaults):
+```yaml
+apiKey:
+  decrypt:
+    encryptedValue: "{{ encryptedApiKey }}"
+    key: "{{ encryptionKey }}"             # optional Base64 AES key
+    initializationVector: "{{ iv }}"       # optional Base64 IV
+```
+
+---
+
+## Property Path Syntax (in collection, mapping, variable paths)
+
+Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `a.b.c` | Dot-separated nested path | `order.customer.name` |
+| `prop?` | Optional access (null if missing) | `order.customer?.name?` |
+| `list[0]` | Array index | `items[0]` |
+| `list[^1]` | Index from end (last item) | `items[^1]` |
+| `list[*]` | Flatten/wildcard (all items) | `containers[*].commodities` |
+| `list[**]` | Recursive flatten (all depths) | `containerCommodities[**]` |
+| `list[-1]` | Depth filter (leaves only) | `tree[**][-1]` |
+| `list[condition]` | Filter by condition | `items[status=Active]` |
+| `dict['key']` | Dictionary key access | `customValues['myField']` |
+| `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
+| `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |
+| `list[*].{alias:_.parent}` | Field selector referencing parent | `items[*].{parentId:_.orderId}` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "description": "Schema validation package for CargoXplorer YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",