yaml-flow 5.4.2 → 7.0.0

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+import { readStdinJson, runBoardCli, toFsRef, writeFailure, writeResult } from './_board-cli.js';
 
 try {
   const input = await readStdinJson();
@@ -8,16 +8,12 @@ try {
 
   if (!boardDir) {
     writeFailure('BOARD_DIR is required');
-    process.exit(0);
   }
 
-  const status = runBoardCli(['status', '--rg', boardDir], { capture: true });
+  const status = runBoardCli(['status', '--base-ref', toFsRef(boardDir)], { capture: true });
 
   writeResult({
-    result: 'success',
-    data: {
-      status,
-    },
+    status,
   });
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/update-holdings-cli.js

@@ -2,7 +2,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+import { readStdinJson, runBoardCli, runCardStoreCliWithInput, toFsRef, writeFailure, writeResult } from './_board-cli.js';
 
 try {
   const input = await readStdinJson();
@@ -12,7 +12,6 @@ try {
 
   if (!boardDir || !cardsDir || !Array.isArray(holdings)) {
     writeFailure('BOARD_DIR, CARDS_DIR and HOLDINGS array are required');
-    process.exit(0);
   }
 
   const cardPath = path.join(cardsDir, 'portfolio-form.json');
@@ -22,14 +21,16 @@ try {
   card.card_data.holdings = holdings;
   fs.writeFileSync(cardPath, `${JSON.stringify(card, null, 2)}\n`, 'utf-8');
 
-  runBoardCli(['upsert-card', '--rg', boardDir, '--card', cardPath, '--restart']);
+  const baseRef = toFsRef(boardDir);
+  runCardStoreCliWithInput(
+    ['set', '--store-ref', baseRef],
+    JSON.stringify(card),
+  );
+  runBoardCli(['upsert-card', '--base-ref', baseRef, '--card-id', card.id, '--restart']);
 
   writeResult({
-    result: 'success',
-    data: {
-      saved: true,
-      holdings_count: holdings.length,
-    },
+    saved: true,
+    holdings_count: holdings.length,
   });
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/wait-completed-cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+import { readStdinJson, runBoardCli, toFsRef, writeFailure, writeResult } from './_board-cli.js';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -16,22 +16,22 @@ try {
 
   if (!boardDir || tasks.length === 0) {
     writeFailure('BOARD_DIR and COMPLETION_TASKS are required');
-    process.exit(0);
   }
 
   const started = Date.now();
 
   while (Date.now() - started < timeoutMs) {
-    const status = runBoardCli(['status', '--rg', boardDir], { capture: true });
-    const complete = tasks.every((task) => new RegExp(`\\bcompleted\\s+${task}\\b`).test(status));
+    const statusJson = runBoardCli(['status', '--base-ref', toFsRef(boardDir)], { capture: true });
+    let cards = [];
+    try {
+      cards = JSON.parse(statusJson)?.data?.cards ?? [];
+    } catch { /* ignore parse errors */ }
+    const complete = tasks.every((task) => cards.some(c => c.name === task && c.status === 'completed'));
 
     if (complete) {
       writeResult({
-        result: 'success',
-        data: {
-          label,
-          completed: true,
-        },
+        label,
+        completed: true,
       });
       process.exit(0);
     }
@@ -39,14 +39,9 @@ try {
     await sleep(pollMs);
   }
 
-  writeResult({
-    result: 'timeout',
-    data: {
-      label,
-      completed: false,
-      error: `${label}: timed out waiting for completion`,
-    },
-  });
+  // Timeout — exit non-zero
+  process.stderr.write(`${label}: timed out waiting for completion`);
+  process.exit(1);
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);
   writeFailure(message);

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/write-prices-cli.js

@@ -12,7 +12,6 @@ try {
 
   if (!boardDirInput || !prices || typeof prices !== 'object' || Array.isArray(prices)) {
     writeFailure('BOARD_DIR and PRICES object are required');
-    process.exit(0);
   }
 
   const boardDir = path.resolve(boardDirInput);
@@ -23,11 +22,8 @@ try {
   fs.writeFileSync(tmpFile, payload, 'utf-8');
 
   writeResult({
-    result: 'success',
-    data: {
-      wrote: true,
-      tmp_file: tmpFile,
-    },
+    wrote: true,
+    tmp_file: tmpFile,
   });
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);

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

@@ -0,0 +1,107 @@
+"""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 base64
+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 to_fs_ref(value: str) -> str:
+    payload = json.dumps({"kind": "fs-path", "value": value}, separators=(",", ":")).encode("utf-8")
+    return "b64:" + base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+
+
+def _normalize_args(args: list[str]) -> list[str]:
+    return list(args)
+
+
+def run_board_pycli(args: list[str], *, capture: bool = False) -> str:
+    cmd = [sys.executable, str(BOARD_PYCLI), *_normalize_args(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), *_normalize_args(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), *_normalize_args(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,51 @@
+#!/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,
+    to_fs_ref,
+    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 = to_fs_ref(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,45 @@
+#!/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,
+    to_fs_ref,
+    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 = to_fs_ref(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,71 @@
+#!/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,
+    to_fs_ref,
+    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 = to_fs_ref(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]