yaml-flow 5.4.2 → 6.0.0

package/examples/cli/step-machine-cli/portfolio-tracker/handlers-py/_board_pycli.py

@@ -0,0 +1,97 @@
+"""Shared helpers for step-machine portfolio-tracker pycli handlers.
+
+Each handler reads a JSON object from stdin and writes a JSON object to stdout.
+Result schema: {"result": "success" | "failure" | "timeout", "data"?: {...}, "error"?: "..."}
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+# Repo root layout (standalone or source tree):
+#   <root>/pycli/main/board_live_cards_pycli.py
+#   <root>/pycli/main/card_store_pycli.py
+#   <root>/dist/pycli/quickjs-board-runtime.global.js
+_HERE = Path(__file__).resolve().parent
+_REPO_ROOT = _HERE.parents[4]
+
+BOARD_PYCLI = _REPO_ROOT / "pycli" / "main" / "board_live_cards_pycli.py"
+CARD_STORE_PYCLI = _REPO_ROOT / "pycli" / "main" / "card_store_pycli.py"
+QUICKJS_BUNDLE = _REPO_ROOT / "dist" / "pycli" / "quickjs-board-runtime.global.js"
+
+
+def read_stdin_json() -> dict[str, Any]:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return {}
+    return json.loads(raw)
+
+
+def write_result(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, ensure_ascii=True))
+    sys.stdout.flush()
+
+
+def write_failure(message: str) -> None:
+    write_result({"result": "failure", "error": message})
+
+
+def _hidden_kwargs() -> dict[str, Any]:
+    kwargs: dict[str, Any] = {}
+    if os.name == "nt":
+        startupinfo = subprocess.STARTUPINFO()
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+        kwargs["startupinfo"] = startupinfo
+        kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+    return kwargs
+
+
+def run_board_pycli(args: list[str], *, capture: bool = False) -> str:
+    cmd = [sys.executable, str(BOARD_PYCLI), *args, "--bundle", str(QUICKJS_BUNDLE)]
+    proc = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+        **_hidden_kwargs(),
+    )
+    if proc.returncode != 0:
+        msg = (proc.stderr or proc.stdout or "no output").strip()
+        raise RuntimeError(f"board_live_cards_pycli failed ({proc.returncode}): {msg}")
+    return proc.stdout if capture else ""
+
+
+def run_board_pycli_with_input(args: list[str], input_json: str) -> str:
+    cmd = [sys.executable, str(BOARD_PYCLI), *args, "--bundle", str(QUICKJS_BUNDLE)]
+    proc = subprocess.run(
+        cmd,
+        input=input_json,
+        capture_output=True,
+        text=True,
+        check=False,
+        **_hidden_kwargs(),
+    )
+    if proc.returncode != 0:
+        msg = (proc.stderr or proc.stdout or "no output").strip()
+        raise RuntimeError(f"board_live_cards_pycli failed ({proc.returncode}): {msg}")
+    return proc.stdout
+
+
+def run_card_store_pycli_with_input(args: list[str], input_json: str) -> str:
+    cmd = [sys.executable, str(CARD_STORE_PYCLI), *args]
+    proc = subprocess.run(
+        cmd,
+        input=input_json,
+        capture_output=True,
+        text=True,
+        check=False,
+        **_hidden_kwargs(),
+    )
+    if proc.returncode != 0:
+        msg = (proc.stderr or proc.stdout or "no output").strip()
+        raise RuntimeError(f"card_store_pycli failed ({proc.returncode}): {msg}")
+    return proc.stdout

package/examples/cli/step-machine-cli/portfolio-tracker/handlers-py/add-cards.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Write all cards to card-store and upsert them onto the board (pycli)."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _board_pycli import (  # noqa: E402
+    read_stdin_json,
+    run_board_pycli,
+    run_card_store_pycli_with_input,
+    write_failure,
+    write_result,
+)
+
+
+def main() -> int:
+    try:
+        payload = read_stdin_json()
+        board_dir = str(payload.get("BOARD_DIR", "")).strip()
+        cards = payload.get("CARDS")
+        if not isinstance(cards, list):
+            cards = []
+
+        if not board_dir or not cards:
+            write_failure("BOARD_DIR and CARDS (array) are required")
+            return 0
+
+        base_ref = f"::fs-path::{board_dir}"
+
+        run_card_store_pycli_with_input(
+            ["set", "--store-ref", base_ref],
+            json.dumps(cards, ensure_ascii=True),
+        )
+        run_board_pycli(["upsert-card", "--base-ref", base_ref, "--all"])
+
+        write_result({
+            "result": "success",
+            "data": {"board_dir": board_dir, "count": len(cards)},
+        })
+        return 0
+    except Exception as exc:
+        write_failure(str(exc))
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/examples/cli/step-machine-cli/portfolio-tracker/handlers-py/init-board.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Initialize the board with card-store and outputs-store refs (pycli)."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _board_pycli import (  # noqa: E402
+    read_stdin_json,
+    run_board_pycli,
+    write_failure,
+    write_result,
+)
+
+
+def main() -> int:
+    try:
+        payload = read_stdin_json()
+        board_dir = str(payload.get("BOARD_DIR", "")).strip()
+        if not board_dir:
+            write_failure("BOARD_DIR is required")
+            return 0
+
+        base_ref = f"::fs-path::{board_dir}"
+        run_board_pycli([
+            "init",
+            "--base-ref", base_ref,
+            "--card-store-ref", base_ref,
+            "--outputs-store-ref", base_ref,
+        ])
+
+        write_result({
+            "result": "success",
+            "data": {"board_dir": board_dir, "message": f"initialized {board_dir}"},
+        })
+        return 0
+    except Exception as exc:
+        write_failure(str(exc))
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/examples/cli/step-machine-cli/portfolio-tracker/handlers-py/poll-status.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Poll board status until all expected cards reach `completed` (pycli)."""
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _board_pycli import (  # noqa: E402
+    read_stdin_json,
+    run_board_pycli,
+    write_failure,
+    write_result,
+)
+
+
+def main() -> int:
+    try:
+        payload = read_stdin_json()
+        board_dir = str(payload.get("BOARD_DIR", "")).strip()
+        expected = int(payload.get("EXPECTED_CARD_COUNT") or 0)
+        timeout_ms = int(payload.get("TIMEOUT_MS") or 30_000)
+        poll_ms = int(payload.get("POLL_MS") or 500)
+
+        if not board_dir or expected <= 0:
+            write_failure("BOARD_DIR and EXPECTED_CARD_COUNT are required")
+            return 0
+
+        base_ref = f"::fs-path::{board_dir}"
+        deadline = time.monotonic() + (timeout_ms / 1000)
+
+        while time.monotonic() < deadline:
+            raw = run_board_pycli(["status", "--base-ref", base_ref], capture=True)
+            cards = []
+            try:
+                cards = json.loads(raw).get("data", {}).get("cards", []) or []
+            except Exception:
+                cards = []
+
+            completed = [c for c in cards if c.get("status") == "completed"]
+            if len(cards) >= expected and len(completed) >= expected:
+                write_result({
+                    "result": "success",
+                    "data": {
+                        "completed": True,
+                        "card_count": len(cards),
+                        "completed_count": len(completed),
+                    },
+                })
+                return 0
+
+            time.sleep(poll_ms / 1000)
+
+        write_result({
+            "result": "timeout",
+            "data": {
+                "completed": False,
+                "error": f"timed out waiting for {expected} cards to complete",
+            },
+        })
+        return 0
+    except Exception as exc:
+        write_failure(str(exc))
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/examples/cli/step-machine-cli/portfolio-tracker/handlers-py/reset-board-dir.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Reset (rm -rf) the board runtime directory."""
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _board_pycli import read_stdin_json, write_failure, write_result  # noqa: E402
+
+
+def main() -> int:
+    try:
+        payload = read_stdin_json()
+        board_dir_input = str(payload.get("BOARD_DIR", "")).strip()
+        if not board_dir_input:
+            write_failure("BOARD_DIR is required")
+            return 0
+
+        board_dir = Path(board_dir_input).resolve()
+        if board_dir.exists():
+            shutil.rmtree(board_dir, ignore_errors=True)
+
+        write_result({
+            "result": "success",
+            "data": {"board_dir": str(board_dir), "reset": True},
+        })
+        return 0
+    except Exception as exc:
+        write_failure(str(exc))
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,26 @@
+id: inline-python-demo
+settings:
+  start_step: greet
+  max_total_steps: 5
+
+steps:
+  greet:
+    description: Build a greeting message using Python inline handler
+    handler:
+      inline: greet_user
+    transitions:
+      success: add
+
+  add:
+    description: Add two numbers with Python inline handler
+    expects_data: [a, b]
+    produces_data: [total]
+    handler:
+      inline: add_numbers
+    transitions:
+      success: done
+
+terminal_states:
+  done:
+    return_intent: success
+    return_artifacts: [message, total]

package/examples/cli/step-machine-cli/portfolio-tracker/inline-python-handlers.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+
+def greet_user(input_obj, ctx=None):
+    payload = input_obj if isinstance(input_obj, dict) else {}
+    name = payload.get("name", "world")
+    return {
+        "result": "success",
+        "data": {
+            "message": f"Hello, {name}!",
+        },
+    }
+
+
+def add_numbers(input_obj, ctx=None):
+    payload = input_obj if isinstance(input_obj, dict) else {}
+    a = payload.get("a", 0)
+    b = payload.get("b", 0)
+    try:
+        total = float(a) + float(b)
+    except Exception:
+        return {
+            "result": "failure",
+            "data": {"error": f"Cannot add values: a={a!r}, b={b!r}"},
+        }
+
+    if total.is_integer():
+        total = int(total)
+
+    return {
+        "result": "success",
+        "data": {"total": total},
+    }
+
+
+handlers = {
+    "greet_user": greet_user,
+    "add_numbers": add_numbers,
+}

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

@@ -0,0 +1,80 @@
+id: portfolio-tracker-step-machine-pycli
+settings:
+  start_step: t0_reset_board
+  max_total_steps: 30
+  timeout_ms: 120000
+
+steps:
+  t0_reset_board:
+    description: Reset board runtime directory for idempotent reruns
+    expects_data: [runtime_root, board_name]
+    produces_data: [board_dir]
+    handler:
+      cli: python ./handlers-py/reset-board-dir.py
+      input-transforms:
+        BOARD_DIR: runtime_root & "/" & board_name
+      output-transforms:
+        board_dir: data.board_dir
+    transitions:
+      success: t0_init_board
+    failure_transitions:
+      failure: failed_state
+
+  t0_init_board:
+    description: Initialize board with card-store and outputs-store refs (pycli)
+    expects_data: [board_dir]
+    produces_data: [board_dir]
+    handler:
+      cli: python ./handlers-py/init-board.py
+      input-transforms:
+        BOARD_DIR: board_dir
+      output-transforms:
+        board_dir: data.board_dir
+    transitions:
+      success: t1_add_cards
+    failure_transitions:
+      failure: failed_state
+
+  t1_add_cards:
+    description: Add cards via card-store set and upsert-card --all (pycli)
+    expects_data: [board_dir, cards]
+    produces_data: [cards_added]
+    handler:
+      cli: python ./handlers-py/add-cards.py
+      input-transforms:
+        BOARD_DIR: board_dir
+        CARDS: cards
+      output-transforms:
+        cards_added: data.count
+    transitions:
+      success: t2_poll_status
+    failure_transitions:
+      failure: failed_state
+
+  t2_poll_status:
+    description: Poll board status until all cards are completed (pycli)
+    expects_data: [board_dir, expected_card_count]
+    produces_data: [all_completed]
+    handler:
+      cli: python ./handlers-py/poll-status.py
+      input-transforms:
+        BOARD_DIR: board_dir
+        EXPECTED_CARD_COUNT: expected_card_count
+        TIMEOUT_MS: "30000"
+        POLL_MS: "500"
+      output-transforms:
+        all_completed: data.completed
+    transitions:
+      success: success_state
+    failure_transitions:
+      timeout: failed_state
+      failure: failed_state
+
+terminal_states:
+  success_state:
+    return_intent: success
+    return_artifacts: [board_dir, cards_added, all_completed]
+
+  failed_state:
+    return_intent: failure
+    return_artifacts: [error, board_dir]

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:
@@ -24,204 +21,60 @@ steps:
       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
+      cli: node ./handlers/init-board-cli.js
       input-transforms:
         BOARD_DIR: board_dir
       output-transforms:
-        board_dir: BOARD_DIR
-    transitions:
-      success: t0_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]
-    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
-    transitions:
-      success: t1_write_prices
-    failure_transitions:
-      failure: failed_state
-
-  t1_write_prices:
-    description: Write baseline prices
-    expects_data: [board_dir, prices_t1]
-    produces_data: [prices_written_t1]
-    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
+        board_dir: data.board_dir
     transitions:
-      success: t3_write_prices
+      success: t1_add_cards
     failure_transitions:
       failure: failed_state
 
-  t3_write_prices:
-    description: Write final refreshed prices
-    expects_data: [board_dir, prices_t3]
-    produces_data: [prices_written_t3]
+  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 ./handlers/write-prices-cli.js
+      cli: node ./handlers/add-cards-cli.js
       input-transforms:
         BOARD_DIR: board_dir
-        TMP_FILE_NAME: TMP_FILE_NAME
-        PRICES: prices_t3
+        CARDS: cards
       output-transforms:
-        prices_written_t3: data.wrote
+        cards_added: data.count
     transitions:
-      success: t3_wait
+      success: t2_poll_status
     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]
+  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/wait-completed-cli.js
+      cli: node ./handlers/poll-status-cli.js
       input-transforms:
         BOARD_DIR: board_dir
-        COMPLETION_TASKS: completion_tasks
-        LABEL: "'T3'"
-        TIMEOUT_MS: "60000"
+        EXPECTED_CARD_COUNT: expected_card_count
+        TIMEOUT_MS: "30000"
         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
+        all_completed: data.completed
     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]