yaml-flow 5.4.2 → 7.0.0

package/examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml

@@ -1,11 +1,8 @@
 id: portfolio-tracker-step-machine
-handler_vars:
-  BOARDCLI_CMD: ../../../../board-live-cards-cli.js
-  TMP_FILE_NAME: tmp_file1
 settings:
   start_step: t0_reset_board
-  max_total_steps: 150
-  timeout_ms: 300000
+  max_total_steps: 30
+  timeout_ms: 120000
 
 steps:
   t0_reset_board:
@@ -13,215 +10,67 @@ steps:
     expects_data: [runtime_root, board_name]
     produces_data: [board_dir]
     handler:
-      cli: node ./handlers/reset-board-dir-cli.js
-      input-transforms:
-        BOARD_DIR: runtime_root & "/" & board_name
-      output-transforms:
-        board_dir: data.board_dir
+      type: ref
+      howToRun: local-node
+      whatToRun: "::fs-path::./handlers/reset-board-dir-cli.js"
+      argsMassaging:
+        bodyTemplate: "{ 'BOARD_DIR': runtime_root & '/' & board_name }"
     transitions:
       success: t0_init_board
     failure_transitions:
       failure: failed_state
 
   t0_init_board:
-    description: Initialize board runtime directory
+    description: Initialize board with card-store and outputs-store refs
     expects_data: [board_dir]
     produces_data: [board_dir]
     handler:
-      cli: node %%BOARDCLI_CMD%% init "%%BOARD_DIR%%"
-      result-mode: exit-code
-      input-transforms:
-        BOARD_DIR: board_dir
-      output-transforms:
-        board_dir: BOARD_DIR
+      type: ref
+      howToRun: local-node
+      whatToRun: "::fs-path::./handlers/init-board-cli.js"
+      argsMassaging:
+        bodyTemplate: "{ 'BOARD_DIR': board_dir }"
     transitions:
-      success: t0_add_cards
+      success: t1_add_cards
     failure_transitions:
       failure: failed_state
 
-  t0_add_cards:
-    description: Add local portfolio cards
-    expects_data: [board_dir, cards_template_dir]
-    produces_data: [cards_dir]
+  t1_add_cards:
+    description: Add 3 cards via card-store set and upsert-card --all
+    expects_data: [board_dir, cards]
+    produces_data: [cards_added]
     handler:
-      cli: node %%BOARDCLI_CMD%% upsert-card --rg "%%BOARD_DIR%%" --card-glob "%%CARDS_GLOB%%"
-      result-mode: exit-code
-      input-transforms:
-        BOARD_DIR: board_dir
-        CARDS_GLOB: cards_template_dir & "/*.json"
-      output-transforms:
-        cards_dir: cards_template_dir
+      type: ref
+      howToRun: local-node
+      whatToRun: "::fs-path::./handlers/add-cards-cli.js"
+      argsMassaging:
+        bodyTemplate: "{ 'BOARD_DIR': board_dir, 'CARDS': cards }"
     transitions:
-      success: t1_write_prices
+      success: t2_poll_status
     failure_transitions:
       failure: failed_state
 
-  t1_write_prices:
-    description: Write baseline prices
-    expects_data: [board_dir, prices_t1]
-    produces_data: [prices_written_t1]
+  t2_poll_status:
+    description: Poll board status until all 3 cards are completed
+    expects_data: [board_dir, expected_card_count]
+    produces_data: [all_completed]
     handler:
-      cli: node ./handlers/write-prices-cli.js
-      input-transforms:
-        BOARD_DIR: board_dir
-        TMP_FILE_NAME: TMP_FILE_NAME
-        PRICES: prices_t1
-      output-transforms:
-        prices_written_t1: data.wrote
-    transitions:
-      success: t1_wait
-    failure_transitions:
-      failure: failed_state
-
-  t1_wait:
-    description: Wait for cards to complete after T1
-    expects_data: [board_dir, completion_tasks]
-    produces_data: [t1_done]
-    handler:
-      cli: node ./handlers/wait-completed-cli.js
-      input-transforms:
-        BOARD_DIR: board_dir
-        COMPLETION_TASKS: completion_tasks
-        LABEL: "'T1'"
-        TIMEOUT_MS: "60000"
-        POLL_MS: "500"
-      output-transforms:
-        t1_done: data.completed
-    transitions:
-      success: t2_update_holdings
-    failure_transitions:
-      timeout: failed_state
-      failure: failed_state
-
-  t2_update_holdings:
-    description: Add GOOG position to holdings
-    expects_data: [board_dir, cards_dir, holdings_t2]
-    produces_data: [t2_holdings_saved]
-    handler:
-      cli: node ./handlers/update-holdings-cli.js
-      input-transforms:
-        BOARD_DIR: board_dir
-        CARDS_DIR: cards_dir
-        HOLDINGS: holdings_t2
-      output-transforms:
-        t2_holdings_saved: data.saved
-    transitions:
-      success: t2_write_prices
-    failure_transitions:
-      failure: failed_state
-
-  t2_write_prices:
-    description: Write prices after T2 holdings update
-    expects_data: [board_dir, prices_t2]
-    produces_data: [prices_written_t2]
-    handler:
-      cli: node ./handlers/write-prices-cli.js
-      input-transforms:
-        BOARD_DIR: board_dir
-        TMP_FILE_NAME: TMP_FILE_NAME
-        PRICES: prices_t2
-      output-transforms:
-        prices_written_t2: data.wrote
-    transitions:
-      success: t2_wait
-    failure_transitions:
-      failure: failed_state
-
-  t2_wait:
-    description: Wait for cards to complete after T2
-    expects_data: [board_dir, completion_tasks]
-    produces_data: [t2_done]
-    handler:
-      cli: node ./handlers/wait-completed-cli.js
-      input-transforms:
-        BOARD_DIR: board_dir
-        COMPLETION_TASKS: completion_tasks
-        LABEL: "'T2'"
-        TIMEOUT_MS: "60000"
-        POLL_MS: "500"
-      output-transforms:
-        t2_done: data.completed
-    transitions:
-      success: t3_retrigger
-    failure_transitions:
-      timeout: failed_state
-      failure: failed_state
-
-  t3_retrigger:
-    description: Retrigger price-fetch task
-    expects_data: [board_dir, price_fetch_task]
-    produces_data: [t3_retriggered]
-    handler:
-      cli: node %%BOARDCLI_CMD%% retrigger --rg "%%BOARD_DIR%%" --task "%%TASK%%"
-      result-mode: exit-code
-      input-transforms:
-        BOARD_DIR: board_dir
-        TASK: price_fetch_task
-      output-transforms:
-        t3_retriggered: true
-    transitions:
-      success: t3_write_prices
-    failure_transitions:
-      failure: failed_state
-
-  t3_write_prices:
-    description: Write final refreshed prices
-    expects_data: [board_dir, prices_t3]
-    produces_data: [prices_written_t3]
-    handler:
-      cli: node ./handlers/write-prices-cli.js
-      input-transforms:
-        BOARD_DIR: board_dir
-        TMP_FILE_NAME: TMP_FILE_NAME
-        PRICES: prices_t3
-      output-transforms:
-        prices_written_t3: data.wrote
-    transitions:
-      success: t3_wait
-    failure_transitions:
-      failure: failed_state
-
-  t3_wait:
-    description: Wait for cards to complete after T3
-    expects_data: [board_dir, completion_tasks]
-    produces_data: [t3_done]
-    handler:
-      cli: node ./handlers/wait-completed-cli.js
-      input-transforms:
-        BOARD_DIR: board_dir
-        COMPLETION_TASKS: completion_tasks
-        LABEL: "'T3'"
-        TIMEOUT_MS: "60000"
-        POLL_MS: "500"
-      output-transforms:
-        t3_done: data.completed
-    transitions:
-      success: t4_status
-    failure_transitions:
-      timeout: failed_state
-      failure: failed_state
-
-  t4_status:
-    description: Capture final board status
-    expects_data: [board_dir]
-    produces_data: [final_status]
-    handler:
-      cli: node %%BOARDCLI_CMD%% status --rg "%%BOARD_DIR%%"
-      result-mode: exit-code
-      input-transforms:
-        BOARD_DIR: board_dir
-      output-transforms:
-        final_status: stdout
+      type: ref
+      howToRun: local-node
+      whatToRun: "::fs-path::./handlers/poll-status-cli.js"
+      argsMassaging:
+        bodyTemplate: "{ 'BOARD_DIR': board_dir, 'EXPECTED_CARD_COUNT': expected_card_count, 'TIMEOUT_MS': '30000', 'POLL_MS': '500' }"
     transitions:
       success: success_state
     failure_transitions:
+      timeout: failed_state
       failure: failed_state
 
 terminal_states:
   success_state:
     return_intent: success
-    return_artifacts: [board_dir, t1_done, t2_done, t3_done, final_status]
+    return_artifacts: [board_dir, cards_added, all_completed]
 
   failed_state:
     return_intent: failure
-    return_artifacts: [error, board_dir, final_status]
+    return_artifacts: [error, board_dir]

package/examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.input.json

@@ -1,38 +1,44 @@
 {
   "runtime_root": "./runtime",
   "board_name": "portfolio-tracker-board",
-  "cards_template_dir": "./cards",
-  "completion_tasks": [
-    "portfolio-form",
-    "price-fetch",
-    "holdings-table",
-    "portfolio-value"
-  ],
-  "price_fetch_task": "price-fetch",
-  "prices_t1": {
-    "AAPL": 198.5,
-    "MSFT": 425.3,
-    "GOOG": 178.9,
-    "AMZN": 192.4,
-    "TSLA": 168.75
-  },
-  "holdings_t2": [
-    { "symbol": "AAPL", "qty": 50 },
-    { "symbol": "MSFT", "qty": 30 },
-    { "symbol": "GOOG", "qty": 100 }
-  ],
-  "prices_t2": {
-    "AAPL": 198.5,
-    "MSFT": 425.3,
-    "GOOG": 178.9,
-    "AMZN": 192.4,
-    "TSLA": 168.75
-  },
-  "prices_t3": {
-    "AAPL": 205,
-    "MSFT": 425.3,
-    "GOOG": 178.9,
-    "AMZN": 192.4,
-    "TSLA": 168.75
-  }
+  "expected_card_count": 3,
+  "cards": [
+    {
+      "id": "portfolio-form",
+      "meta": { "title": "Portfolio Holdings Form" },
+      "provides": [{ "bindTo": "holdings", "ref": "card_data.holdings" }],
+      "card_data": {
+        "holdings": [
+          { "symbol": "AAPL", "qty": 50 },
+          { "symbol": "MSFT", "qty": 30 },
+          { "symbol": "GOOG", "qty": 100 }
+        ]
+      }
+    },
+    {
+      "id": "prices-mock",
+      "meta": { "title": "Mock Market Prices" },
+      "provides": [{ "bindTo": "prices", "ref": "card_data.prices" }],
+      "card_data": {
+        "prices": {
+          "AAPL": 198.5,
+          "MSFT": 425.3,
+          "GOOG": 178.9
+        }
+      }
+    },
+    {
+      "id": "portfolio-value",
+      "meta": { "title": "Portfolio Total Value" },
+      "requires": ["holdings", "prices"],
+      "provides": [{ "bindTo": "totalValue", "ref": "computed_values.totalValue" }],
+      "card_data": {},
+      "compute": [
+        {
+          "bindTo": "totalValue",
+          "expr": "$sum($map(requires.holdings, function($h) { $h.qty * $lookup(requires.prices, $h.symbol) }))"
+        }
+      ]
+    }
+  ]
 }

package/examples/cli/step-machine-cli/portfolio-tracker/run-inline-python-demo-pycli.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    here = Path(__file__).resolve().parent
+    repo_root = here.parents[3]
+
+    pycli = repo_root / "pycli" / "main" / "step_machine_pycli.py"
+    flow = here / "inline-python-demo.flow.yaml"
+
+    initial_data = {
+        "name": "Ada",
+        "a": 7,
+        "b": 5,
+    }
+
+    cmd = [
+        sys.executable,
+        str(pycli),
+        str(flow),
+        "--initial-data",
+        json.dumps(initial_data, ensure_ascii=True),
+        "--store",
+        "memory",
+    ]
+
+    proc = subprocess.run(
+        cmd,
+        cwd=str(here),
+        shell=False,
+        check=False,
+    )
+    return proc.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/examples/cli/step-machine-cli/portfolio-tracker/run-portfolio-tracker-pycli.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run the step-machine portfolio tracker example via step_machine_pycli.py",
+    )
+    parser.add_argument(
+        "action",
+        nargs="?",
+        choices=["run", "pause", "resume", "status"],
+        default="run",
+        help="Operation to perform (default: run)",
+    )
+    return parser
+
+
+def main() -> int:
+    args = _build_parser().parse_args()
+
+    here = Path(__file__).resolve().parent
+    repo_root = here.parents[3]
+    pycli = repo_root / "pycli" / "main" / "step_machine_pycli.py"
+    flow = here / "portfolio-tracker-pycli.flow.yaml"
+    input_json = here / "portfolio-tracker.input.json"
+
+    temp_root = Path(tempfile.gettempdir()) / "yaml-flow-step-machine-portfolio-tracker"
+    store_dir = temp_root / "store"
+    runtime_root = temp_root / "runtime"
+
+    cmd = [
+        sys.executable,
+        str(pycli),
+        "--store",
+        "file",
+        "--store-dir",
+        str(store_dir),
+    ]
+
+    if args.action in ("run", "resume"):
+        cmd.insert(2, str(flow))
+
+    if args.action == "run":
+        payload = json.loads(input_json.read_text(encoding="utf-8"))
+        payload["runtime_root"] = runtime_root.as_posix()
+        cmd.extend(["--initial-data", json.dumps(payload, ensure_ascii=True)])
+    elif args.action == "resume":
+        cmd.append("--resume")
+    elif args.action == "pause":
+        cmd.append("--pause")
+    elif args.action == "status":
+        cmd.append("--status")
+
+    proc = subprocess.run(
+        cmd,
+        cwd=str(here),
+        shell=False,
+        check=False,
+        env={
+            **os.environ,
+            "PATH": str(Path(sys.executable).parent) + os.pathsep + os.environ.get("PATH", ""),
+        },
+    )
+    return proc.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/examples/cli/step-machine-cli/portfolio-tracker/run-portfolio-tracker.bat

@@ -2,7 +2,6 @@
 setlocal
 cd /d "%~dp0"
 
-set "BOARD_LIVE_CARDS_NO_SPAWN=1"
 set "EXAMPLE_TEMP_ROOT=%TEMP%\yaml-flow-step-machine-portfolio-tracker"
 set "STORE_DIR=%EXAMPLE_TEMP_ROOT%\store"
 set "RUNTIME_ROOT=%EXAMPLE_TEMP_ROOT%\runtime"
@@ -25,5 +24,5 @@ node ..\..\..\..\step-machine-cli.js --store file --store-dir "%STORE_DIR%" --st
 exit /b %ERRORLEVEL%
 
 :run
-node -e "const fs=require('fs');const cp=require('child_process');const raw=JSON.parse(fs.readFileSync('portfolio-tracker.input.json','utf8'));raw.runtime_root=(process.env.RUNTIME_ROOT||'').replace(/\\/g,'/');const input=JSON.stringify(raw);const r=cp.spawnSync(process.execPath,['..\\..\\..\\..\\step-machine-cli.js','portfolio-tracker.flow.yaml','--store','file','--store-dir',process.env.STORE_DIR,'--initial-data',input],{stdio:'inherit',windowsHide:true,env:{...process.env,BOARD_LIVE_CARDS_NO_SPAWN:'1'}});process.exit(r.status??1);"
+node -e "const fs=require('fs');const cp=require('child_process');const raw=JSON.parse(fs.readFileSync('portfolio-tracker.input.json','utf8'));raw.runtime_root=(process.env.RUNTIME_ROOT||'').replace(/\\/g,'/');const r=cp.spawnSync(process.execPath,['..\\..\\..\\..\\step-machine-cli.js','portfolio-tracker.flow.yaml','--initial-data',JSON.stringify(raw)],{stdio:'inherit',windowsHide:true,cwd:__dirname});process.exit(r.status??1);"
 exit /b %ERRORLEVEL%

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

@@ -9,27 +9,22 @@ process.stdin.on('data', (chunk) => {
 process.stdin.on('end', () => {
   try {
     const input = JSON.parse(raw || '{}');
-    const boardDirFromArg = process.argv[2] ?? '';
-    const boardDirFromInput = input.BOARD_DIR ?? '';
+    const boardDir = input.BOARD_DIR ?? '';
 
-    if (!boardDirFromArg || !boardDirFromInput || boardDirFromArg !== boardDirFromInput) {
-      process.stdout.write(JSON.stringify({
-        result: 'failure',
-        error: 'BOARD_DIR missing or mismatch between cli arg and stdin payload',
-      }));
+    if (!boardDir) {
+      process.stderr.write('BOARD_DIR missing from input');
+      process.exit(1);
       return;
     }
 
     process.stdout.write(JSON.stringify({
-      result: 'success',
-      data: {
-        message: `initialized ${boardDirFromArg}`,
-        ignored: 'will be filtered by produces_data',
-      },
+      message: `initialized ${boardDir}`,
+      ignored: 'will be filtered by produces_data',
     }));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    process.stdout.write(JSON.stringify({ result: 'failure', error: message }));
+    process.stderr.write(message);
+    process.exit(1);
   }
 });
 

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);
   }
 });