yaml-flow 3.1.1 → 4.0.0

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { readStdinJson, writeFailure, writeResult } from './_board-cli.js';
+
+try {
+  const input = await readStdinJson();
+  const boardDirInput = String(input.BOARD_DIR ?? '').trim();
+  const tmpFileName = String(input.TMP_FILE_NAME ?? '').trim() || 'tmp_file1';
+  const prices = input.PRICES;
+
+  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);
+  const payload = JSON.stringify(prices);
+  const tmpFile = path.join(boardDir, tmpFileName);
+
+  fs.mkdirSync(path.dirname(tmpFile), { recursive: true });
+  fs.writeFileSync(tmpFile, payload, 'utf-8');
+
+  writeResult({
+    result: 'success',
+    data: {
+      wrote: true,
+      tmp_file: tmpFile,
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  writeFailure(message);
+}

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

@@ -0,0 +1,227 @@
+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
+
+steps:
+  t0_reset_board:
+    description: Reset board runtime directory for idempotent reruns
+    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
+    transitions:
+      success: t0_init_board
+    failure_transitions:
+      failure: failed_state
+
+  t0_init_board:
+    description: Initialize board runtime directory
+    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
+    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%% add-cards --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
+    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
+    transitions:
+      success: success_state
+    failure_transitions:
+      failure: failed_state
+
+terminal_states:
+  success_state:
+    return_intent: success
+    return_artifacts: [board_dir, t1_done, t2_done, t3_done, final_status]
+
+  failed_state:
+    return_intent: failure
+    return_artifacts: [error, board_dir, final_status]

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

@@ -0,0 +1,38 @@
+{
+  "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
+  }
+}

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

@@ -0,0 +1,29 @@
+@echo off
+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"
+
+if /I "%~1"=="pause" goto :pause
+if /I "%~1"=="resume" goto :resume
+if /I "%~1"=="status" goto :status
+goto :run
+
+:pause
+node ..\..\..\step-machine-cli.js --store file --store-dir "%STORE_DIR%" --pause
+exit /b %ERRORLEVEL%
+
+:resume
+node ..\..\..\step-machine-cli.js portfolio-tracker.flow.yaml --store file --store-dir "%STORE_DIR%" --resume
+exit /b %ERRORLEVEL%
+
+:status
+node ..\..\..\step-machine-cli.js --store file --store-dir "%STORE_DIR%" --status
+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);"
+exit /b %ERRORLEVEL%

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml-flow",
-  "version": "3.1.1",
+  "version": "4.0.0",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",
@@ -8,6 +8,10 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "board-live-cards-cli": "./board-live-cards-cli.js",
+    "step-machine-cli": "./step-machine-cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -74,6 +78,8 @@
     "./stores/file": false
   },
   "files": [
+    "board-live-cards-cli.js",
+    "step-machine-cli.js",
     "dist",
     "schema",
     "browser",
@@ -90,12 +96,17 @@
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "@types/proper-lockfile": "^4.1.4",
     "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"
   },
   "dependencies": {
     "ajv-formats": "^3.0.1",
+    "fast-glob": "^3.3.3",
+    "jsonata": "^2.1.0",
+    "proper-lockfile": "^4.1.2",
     "yaml": "^2.3.4"
   },
   "optionalDependencies": {

package/schema/board-status.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yaml-flow.dev/schema/board-status.schema.json",
+  "title": "Board Status Object",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "meta", "summary", "cards"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "v1"
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["board"],
+      "properties": {
+        "board": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path"],
+          "properties": {
+            "path": { "type": "string" }
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["card_count", "completed", "eligible", "pending", "blocked", "unresolved"],
+      "properties": {
+        "card_count": { "type": "integer", "minimum": 0 },
+        "completed": { "type": "integer", "minimum": 0 },
+        "eligible": { "type": "integer", "minimum": 0 },
+        "pending": { "type": "integer", "minimum": 0 },
+        "blocked": { "type": "integer", "minimum": 0 },
+        "unresolved": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 },
+        "in_progress": { "type": "integer", "minimum": 0 },
+        "orphan_cards": { "type": "integer", "minimum": 0 },
+        "topology": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["edge_count", "max_fan_out_card", "max_fan_out"],
+          "properties": {
+            "edge_count": { "type": "integer", "minimum": 0 },
+            "max_fan_out_card": { "type": ["string", "null"] },
+            "max_fan_out": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "cards": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "status",
+          "requires",
+          "requires_satisfied",
+          "requires_missing",
+          "provides_declared",
+          "provides_runtime",
+          "blocked_by",
+          "unblocks",
+          "runtime"
+        ],
+        "properties": {
+          "name": { "type": "string" },
+          "status": { "type": "string" },
+          "error": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["message"],
+            "properties": {
+              "message": { "type": "string" },
+              "code": { "type": "string" },
+              "at": { "type": ["string", "null"] },
+              "source": { "type": "string" }
+            }
+          },
+          "requires": { "type": "array", "items": { "type": "string" } },
+          "requires_satisfied": { "type": "array", "items": { "type": "string" } },
+          "requires_missing": { "type": "array", "items": { "type": "string" } },
+          "provides_declared": { "type": "array", "items": { "type": "string" } },
+          "provides_runtime": { "type": "array", "items": { "type": "string" } },
+          "blocked_by": { "type": "array", "items": { "type": "string" } },
+          "unblocks": { "type": "array", "items": { "type": "string" } },
+          "runtime": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "attempt_count",
+              "restart_count",
+              "in_progress_since",
+              "last_transition_at",
+              "last_completed_at",
+              "last_restarted_at",
+              "status_age_ms"
+            ],
+            "properties": {
+              "attempt_count": { "type": "integer", "minimum": 0 },
+              "restart_count": { "type": "integer", "minimum": 0 },
+              "in_progress_since": { "type": ["string", "null"] },
+              "last_transition_at": { "type": ["string", "null"] },
+              "last_completed_at": { "type": ["string", "null"] },
+              "last_restarted_at": { "type": ["string", "null"] },
+              "status_age_ms": { "type": ["integer", "null"], "minimum": 0 }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/flow.schema.json

@@ -77,6 +77,11 @@
           "additionalProperties": { "type": "string" },
           "minProperties": 1
         },
+        "failure_transitions": {
+          "type": "object",
+          "description": "Mapping of failure-like results (e.g. failure, timeout) -> next step name",
+          "additionalProperties": { "type": "string" }
+        },
         "retry": {
           "$ref": "#/definitions/retry_config"
         },