yaml-flow 6.0.0 → 7.0.0

package/examples/cli/step-machine-demo/jsonata-init-board.flow.yaml

@@ -1,21 +1,45 @@
 id: jsonata-init-board-demo
 settings:
-  start_step: t0_init_board
+  start_step: t0_prepare
   max_total_steps: 10
   timeout_ms: 30000
 
 steps:
-  t0_init_board:
-    description: Build board path with JSONata and invoke CLI with command templating
+  t0_prepare:
+    description: Build board path from runtime_root and board_name
     expects_data: [runtime_root, board_name]
+    produces_data: [BOARD_DIR]
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.BOARD_DIR = expects_data.runtime_root & "/" & expects_data.board_name
+        - result = "success"
+    transitions:
+      success: t1_init_board
+      failure: failed_state
+
+  t1_init_board:
+    description: Invoke init-board CLI with BOARD_DIR
+    expects_data: [BOARD_DIR]
+    produces_data: [board_dir, message]
+    handler:
+      type: ref
+      howToRun: local-node
+      whatToRun: "::fs-path::./jsonata-init-board-cli.js"
+    transitions:
+      success: t2_map_output
+      failure: failed_state
+
+  t2_map_output:
+    description: Map CLI output to final field names
+    expects_data: [BOARD_DIR, message]
     produces_data: [board_dir, init_message]
     handler:
-      cli: node ./jsonata-init-board-cli.js "%%BOARD_DIR%%"
-      input-transforms:
-        BOARD_DIR: runtime_root & "/" & board_name
-      output-transforms:
-        board_dir: BOARD_DIR
-        init_message: data.message
+      type: compute-jsonata
+      expr:
+        - data.board_dir = expects_data.BOARD_DIR
+        - data.init_message = expects_data.message
+        - result = "success"
     transitions:
       success: success_state
       failure: failed_state

package/examples/cli/step-machine-demo/one-step-cli-only.flow.yaml

@@ -6,7 +6,9 @@ steps:
     expects_data: [x]
     produces_data: [y]
     handler:
-      cli: node ./step-cli-echo-y.js
+      type: ref
+      howToRun: local-node
+      whatToRun: "::fs-path::./step-cli-echo-y.js"
     transitions:
       success: success_state
       failure: failed_state

package/examples/cli/step-machine-demo/step2-double-cli.js

@@ -13,26 +13,20 @@ process.stdin.on('end', () => {
     const c = Number(input.c);
 
     if (!Number.isFinite(c)) {
-      process.stdout.write(JSON.stringify({
-        result: 'failure',
-        error: 'step2_double requires numeric c',
-      }));
-      process.exit(0);
+      process.stderr.write('step2_double requires numeric c');
+      process.exit(1);
       return;
     }
 
     const d = c * 2;
     process.stdout.write(JSON.stringify({
-      status: 'success',
-      data: {
-        a: 123,
-        d,
-      },
+      a: 123,
+      d,
     }));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    process.stdout.write(JSON.stringify({ result: 'failure', error: message }));
-    process.exit(0);
+    process.stderr.write(message);
+    process.exit(1);
   }
 });
 

package/examples/cli/step-machine-demo/two-step-math.flow.yaml

@@ -4,19 +4,81 @@ settings:
   max_total_steps: 10
   timeout_ms: 10000
 
+# Demonstrates three compute-jsonata techniques:
+#   1. Basic arithmetic with data.* output and explicit result=
+#   2. Chained ternary with local $var binding ($c :=) — range classification and conditional routing
+#   3. $lookup object-switch — route result directly from a map (see switch test in step-machine-cli.test.ts)
+# NOTE: expr items containing ': ' or '{key: value}' must be single-quoted in YAML.
+
 steps:
   step1_add:
     description: Compute c = a + b
     expects_data: [a, b]
     produces_data: [c]
+    input_validations:
+      - $type(a) = "number"
+      - $type(b) = "number"
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.c = expects_data.a + expects_data.b
+        - result = "success"
+    transitions:
+      success: step2_classify
+      failure: failed_state
+
+  step2_classify:
+    description: |
+      Classify c using an object-lookup switch.
+      Routes to low_track / mid_track / high_track based on magnitude.
+    expects_data: [c]
+    produces_data: [band]
+    handler:
+      type: compute-jsonata
+      expr:
+        - 'data.band = ($c := expects_data.c; $c < 10 ? "low" : $c < 100 ? "mid" : "high")'
+        - result = data.band
     transitions:
-      success: step2_double
+      low:  low_track
+      mid:  mid_track
+      high: high_track
+      failure: failed_state
+
+  low_track:
+    description: Small result — multiply by 3
+    expects_data: [c]
+    produces_data: [d]
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.d = expects_data.c * 3
+        - result = "success"
+    transitions:
+      success: success_state
+      failure: failed_state
+
+  mid_track:
+    description: Medium result — multiply by 2
+    expects_data: [c]
+    produces_data: [d]
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.d = expects_data.c * 2
+        - result = "success"
+    transitions:
+      success: success_state
       failure: failed_state
 
-  step2_double:
-    description: Compute d = c * 2
+  high_track:
+    description: Large result — keep as-is (already big enough)
     expects_data: [c]
     produces_data: [d]
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.d = expects_data.c
+        - result = "success"
     transitions:
       success: success_state
       failure: failed_state
@@ -24,7 +86,7 @@ steps:
 terminal_states:
   success_state:
     return_intent: success
-    return_artifacts: [a, b, c, d]
+    return_artifacts: [a, b, c, band, d]
 
   failed_state:
     return_intent: failure

package/examples/cli/step-machine-demo/two-step-mixed.flow.yaml

@@ -6,21 +6,29 @@ settings:
 
 steps:
   step1_add:
-    description: Inline handler computes c = a + b
+    description: Compute step computes c = a + b
     expects_data: [a, b]
-    produces_data: [c, e]
+    produces_data: [c]
+    input_validations:
+      - $type(a) = "number"
+      - $type(b) = "number"
     handler:
-      inline: step1_add
+      type: compute-jsonata
+      expr:
+        - data.c = expects_data.a + expects_data.b
+        - result = "success"
     transitions:
       success: step2_double
       failure: failed_state
 
   step2_double:
-    description: CLI handler computes d = c * 2
+    description: Ref handler computes d = c * 2
     expects_data: [c]
     produces_data: [d, e]
     handler:
-      cli: node ./step2-double-cli.js
+      type: ref
+      howToRun: local-node
+      whatToRun: "::fs-path::./step2-double-cli.js"
     transitions:
       success: success_state
       failure: failed_state

package/examples/example-board/cards/_index.json

@@ -0,0 +1,47 @@
+{
+  "card-portfolio-intelligence": {
+    "key": "card-portfolio-intelligence",
+    "checksum": "card-portfolio-intelligence",
+    "updatedAt": "2026-05-10T09:38:02.181Z"
+  },
+  "card-market-prices": {
+    "key": "card-market-prices",
+    "checksum": "card-market-prices",
+    "updatedAt": "2026-05-10T09:38:02.161Z"
+  },
+  "card-my-identity": {
+    "key": "card-my-identity",
+    "checksum": "card-my-identity",
+    "updatedAt": "2026-05-10T09:38:02.168Z"
+  },
+  "card-portfolio-action": {
+    "key": "card-portfolio-action",
+    "checksum": "card-portfolio-action",
+    "updatedAt": "2026-05-10T09:38:02.174Z"
+  },
+  "card-portfolio-risks": {
+    "key": "card-portfolio-risks",
+    "checksum": "card-portfolio-risks",
+    "updatedAt": "2026-05-10T09:38:02.187Z"
+  },
+  "card-portfolio-value": {
+    "key": "card-portfolio-value",
+    "checksum": "card-portfolio-value",
+    "updatedAt": "2026-05-10T09:38:02.195Z"
+  },
+  "card-portfolio": {
+    "key": "card-portfolio",
+    "checksum": "card-portfolio",
+    "updatedAt": "2026-05-10T09:38:02.201Z"
+  },
+  "card-rebalance-impact": {
+    "key": "card-rebalance-impact",
+    "checksum": "card-rebalance-impact",
+    "updatedAt": "2026-05-10T09:38:02.208Z"
+  },
+  "card-rebalance-sim": {
+    "key": "card-rebalance-sim",
+    "checksum": "card-rebalance-sim",
+    "updatedAt": "2026-05-10T09:38:02.214Z"
+  }
+}

package/examples/example-board/cards/card-market-prices.json

@@ -2,10 +2,15 @@
   "id": "card-market-prices",
   "meta": {
     "title": "Market Prices",
-    "tags": ["prices", "market"],
+    "tags": [
+      "prices",
+      "market"
+    ],
     "desc": "Fetches live prices for portfolio tickers. Publishes enriched quote data for downstream portfolio value calculations."
   },
-  "requires": ["holdings"],
+  "requires": [
+    "holdings"
+  ],
   "source_defs": [
     {
       "bindTo": "quotes",
@@ -24,7 +29,7 @@
   "compute": [
     {
       "bindTo": "normalizedQuotes",
-      "expr": "{ \"quoteResponse\": { \"result\": $map(fetched_sources.quotes, function($r) { $r.chart.result[0].meta.{ \"symbol\": symbol, \"shortName\": longName, \"regularMarketPrice\": regularMarketPrice, \"regularMarketChange\": regularMarketChange, \"regularMarketChangePercent\": regularMarketChangePercent } }), \"error\": null } }"
+      "expr": "{ \"quoteResponse\": { \"result\": $map(fetched_sources.quotes, function($r) { ($m := $r.chart.result[0].meta; $prev := $m.chartPreviousClose; $chg := $m.regularMarketPrice - $prev; { \"symbol\": $m.symbol, \"shortName\": $m.shortName ? $m.shortName : $m.longName, \"regularMarketPrice\": $m.regularMarketPrice, \"regularMarketChange\": $chg, \"regularMarketChangePercent\": $chg / $prev * 100 }) }), \"error\": null } }"
     },
     {
       "bindTo": "prices",
@@ -32,7 +37,10 @@
     }
   ],
   "provides": [
-    { "bindTo": "quotes", "ref": "computed_values.normalizedQuotes" }
+    {
+      "bindTo": "quotes",
+      "ref": "computed_values.normalizedQuotes"
+    }
   ],
   "view": {
     "elements": [
@@ -41,16 +49,32 @@
         "label": "Prices",
         "data": {
           "bind": "computed_values.prices",
-          "columns": ["ticker", "name", "price", "change", "chg_pct"],
+          "columns": [
+            "ticker",
+            "name",
+            "price",
+            "change",
+            "chg_pct"
+          ],
           "sortable": true
         }
       }
     ],
     "layout": {
-      "board": { "col": 4, "order": 2 },
-      "canvas": { "x": 400, "y": 50, "w": 400, "h": 340 }
+      "board": {
+        "col": 4,
+        "order": 2
+      },
+      "canvas": {
+        "x": 400,
+        "y": 50,
+        "w": 400,
+        "h": 340
+      }
     },
-    "features": { "refresh": true }
+    "features": {
+      "refresh": true
+    }
   },
   "card_data": {}
-}
+}

package/examples/example-board/cards/card-my-identity.json

@@ -2,7 +2,10 @@
   "id": "card-my-identity",
   "meta": {
     "title": "My Identity",
-    "tags": ["m365", "workiq"],
+    "tags": [
+      "m365",
+      "workiq"
+    ],
     "desc": "Displays your M365 display name via WorkIQ (Microsoft 365 Copilot)."
   },
   "source_defs": [
@@ -14,15 +17,36 @@
       }
     }
   ],
+  "compute": [
+    {
+      "bindTo": "identity",
+      "expr": "fetched_sources.identity"
+    }
+  ],
   "view": {
     "elements": [
-      { "kind": "markdown", "data": { "bind": "fetched_sources.identity" } }
+      {
+        "kind": "markdown",
+        "data": {
+          "bind": "computed_values.identity"
+        }
+      }
     ],
     "layout": {
-      "board": { "col": 4, "order": 10 },
-      "canvas": { "x": 50, "y": 450, "w": 420, "h": 260 }
+      "board": {
+        "col": 4,
+        "order": 10
+      },
+      "canvas": {
+        "x": 50,
+        "y": 450,
+        "w": 420,
+        "h": 260
+      }
     },
-    "features": { "refresh": true }
+    "features": {
+      "refresh": true
+    }
   },
   "card_data": {}
-}
+}

package/examples/example-board/cards/card-portfolio-action.json

@@ -2,18 +2,36 @@
   "id": "card-portfolio-action",
   "meta": {
     "title": "Action Signal",
-    "tags": ["portfolio", "action"],
+    "tags": [
+      "portfolio",
+      "action"
+    ],
     "desc": "Actionable recommendation sourced from Portfolio Intelligence."
   },
-  "requires": ["portfolio_action"],
+  "requires": [
+    "portfolio_action"
+  ],
   "view": {
     "elements": [
-      { "kind": "markdown", "data": { "bind": "requires.portfolio_action" } }
+      {
+        "kind": "markdown",
+        "data": {
+          "bind": "requires.portfolio_action"
+        }
+      }
     ],
     "layout": {
-      "board": { "col": 4, "order": 6 },
-      "canvas": { "x": 1660, "y": 50, "w": 300, "h": 160 }
+      "board": {
+        "col": 4,
+        "order": 6
+      },
+      "canvas": {
+        "x": 1660,
+        "y": 50,
+        "w": 300,
+        "h": 160
+      }
     }
   },
   "card_data": {}
-}
+}

package/examples/example-board/cards/card-portfolio-intelligence.json

@@ -0,0 +1,97 @@
+{
+  "id": "card-portfolio-intelligence",
+  "meta": {
+    "title": "Portfolio Intelligence",
+    "tags": [
+      "portfolio",
+      "analysis"
+    ],
+    "desc": "AI analysis of portfolio mix and P&L. Publishes structured insights as tokens for downstream risk and action cards."
+  },
+  "requires": [
+    "positions"
+  ],
+  "source_defs": [
+    {
+      "bindTo": "analysis",
+      "outputFile": "card-concentration-analysis.json",
+      "projections": {
+        "positions": "requires.positions"
+      },
+      "copilot": {
+        "prompt_template": "You are a concise equity analyst. Use web search to get today's news and upcoming events for each ticker before answering.\n\nPortfolio positions:\n{{positions}}\n\nFields: ticker, quantity, cost_basis ($), price ($), value ($), gain_$ (unrealised P&L), gain_% (unrealised return), chg_$ (today's position P&L $), chg_pct (today's % move).\n\nIMPORTANT OUTPUT RULES:\n- Return ONLY a valid JSON object. No markdown code fences, no preamble, no trailing text.\n- Start your response with { and end with }.\n- No emojis anywhere.\n- Each value is a Markdown string using - bullet points. No sub-headings inside values.\n- Maximum 40 words per section.\n\n{\n  \"mix\": \"- <dominant holding ticker, % of total, and whether that is a risk>\\n- <sector clustering in one line>\",\n  \"pnl\": \"- Best: <ticker> +X% (+$Y)\\n- Worst: <ticker> +X% (+$Y)\",\n  \"risks\": \"- <TICKER>: <one specific current risk with event name or date>\\n- <TICKER>: ...\\n- (one bullet per position from today's news)\",\n  \"action\": \"- <one sentence: specific action and reason grounded in today's market>\"\n}"
+      }
+    }
+  ],
+  "compute": [
+    {
+      "bindTo": "mix",
+      "expr": "fetched_sources.analysis.mix"
+    },
+    {
+      "bindTo": "pnl",
+      "expr": "fetched_sources.analysis.pnl"
+    },
+    {
+      "bindTo": "risks",
+      "expr": "fetched_sources.analysis.risks"
+    },
+    {
+      "bindTo": "action",
+      "expr": "fetched_sources.analysis.action"
+    }
+  ],
+  "provides": [
+    {
+      "bindTo": "portfolio_mix",
+      "ref": "computed_values.mix"
+    },
+    {
+      "bindTo": "portfolio_pnl",
+      "ref": "computed_values.pnl"
+    },
+    {
+      "bindTo": "portfolio_risks",
+      "ref": "computed_values.risks"
+    },
+    {
+      "bindTo": "portfolio_action",
+      "ref": "computed_values.action"
+    }
+  ],
+  "view": {
+    "elements": [
+      {
+        "kind": "markdown",
+        "label": "Mix",
+        "data": {
+          "bind": "computed_values.mix"
+        }
+      },
+      {
+        "kind": "markdown",
+        "label": "P&L",
+        "data": {
+          "bind": "computed_values.pnl"
+        }
+      }
+    ],
+    "layout": {
+      "board": {
+        "col": 3,
+        "order": 4
+      },
+      "canvas": {
+        "x": 1300,
+        "y": 50,
+        "w": 340,
+        "h": 200
+      }
+    },
+    "features": {
+      "refresh": true,
+      "chat": true
+    }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-portfolio-risks.json

@@ -2,18 +2,36 @@
   "id": "card-portfolio-risks",
   "meta": {
     "title": "Risk Watch",
-    "tags": ["portfolio", "risk"],
+    "tags": [
+      "portfolio",
+      "risk"
+    ],
     "desc": "Per-ticker risk signals sourced from Portfolio Intelligence."
   },
-  "requires": ["portfolio_risks"],
+  "requires": [
+    "portfolio_risks"
+  ],
   "view": {
     "elements": [
-      { "kind": "markdown", "data": { "bind": "requires.portfolio_risks" } }
+      {
+        "kind": "markdown",
+        "data": {
+          "bind": "requires.portfolio_risks"
+        }
+      }
     ],
     "layout": {
-      "board": { "col": 3, "order": 5 },
-      "canvas": { "x": 1300, "y": 270, "w": 340, "h": 220 }
+      "board": {
+        "col": 3,
+        "order": 5
+      },
+      "canvas": {
+        "x": 1300,
+        "y": 270,
+        "w": 340,
+        "h": 220
+      }
     }
   },
   "card_data": {}
-}
+}

package/examples/example-board/cards/card-portfolio-value.json

@@ -2,12 +2,21 @@
   "id": "card-portfolio-value",
   "meta": {
     "title": "Portfolio Value",
-    "tags": ["portfolio", "value"],
+    "tags": [
+      "portfolio",
+      "value"
+    ],
     "desc": "Computes total portfolio value, gainers/losers summary, and per-position P&L from holdings and live market quotes."
   },
-  "requires": ["holdings", "quotes"],
+  "requires": [
+    "holdings",
+    "quotes"
+  ],
   "provides": [
-    { "bindTo": "positions", "ref": "computed_values.positions" }
+    {
+      "bindTo": "positions",
+      "ref": "computed_values.positions"
+    }
   ],
   "compute": [
     {
@@ -36,27 +45,46 @@
       {
         "kind": "metric",
         "label": "Portfolio Value ($)",
-        "data": { "bind": "computed_values.totalValue" }
+        "data": {
+          "bind": "computed_values.totalValue"
+        }
       },
       {
         "kind": "text",
-        "data": { "bind": "computed_values.gainersLosers" }
+        "data": {
+          "bind": "computed_values.gainersLosers"
+        }
       },
       {
         "kind": "table",
         "label": "Positions",
         "data": {
           "bind": "computed_values.positions",
-          "columns": ["ticker", "value", "gain_$", "gain_%"],
+          "columns": [
+            "ticker",
+            "value",
+            "gain_$",
+            "gain_%"
+          ],
           "sortable": true
         }
       }
     ],
     "layout": {
-      "board": { "col": 4, "order": 3 },
-      "canvas": { "x": 840, "y": 50, "w": 420, "h": 380 }
+      "board": {
+        "col": 4,
+        "order": 3
+      },
+      "canvas": {
+        "x": 840,
+        "y": 50,
+        "w": 420,
+        "h": 380
+      }
     },
-    "features": { "chat": true }
+    "features": {
+      "chat": true
+    }
   },
   "card_data": {}
-}
+}