yaml-flow 3.1.0 → 4.0.0

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

@@ -0,0 +1,58 @@
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, '..', '..', '..', '..');
+const boardCliPath = path.join(repoRoot, 'board-live-cards-cli.js');
+
+export function runBoardCli(args, options = {}) {
+  const { capture = false, cwd = process.cwd() } = options;
+  const result = spawnSync(process.execPath, [boardCliPath, ...args], {
+    cwd,
+    encoding: 'utf-8',
+    windowsHide: true,
+    stdio: capture ? 'pipe' : 'pipe',
+    env: {
+      ...process.env,
+      BOARD_LIVE_CARDS_NO_SPAWN: process.env.BOARD_LIVE_CARDS_NO_SPAWN ?? '1',
+      BOARD_DIR: process.env.BOARD_DIR ?? '',
+    },
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to launch board-live-cards-cli: ${result.error.message}`);
+  }
+
+  if ((result.status ?? 1) !== 0) {
+    const stderr = (result.stderr ?? '').trim();
+    const stdout = (result.stdout ?? '').trim();
+    throw new Error(`board-live-cards-cli failed (${result.status}): ${stderr || stdout || 'no output'}`);
+  }
+
+  return capture ? (result.stdout ?? '') : '';
+}
+
+export async function readStdinJson() {
+  let raw = '';
+  process.stdin.setEncoding('utf-8');
+
+  for await (const chunk of process.stdin) {
+    raw += chunk;
+  }
+
+  if (!raw.trim()) {
+    return {};
+  }
+
+  return JSON.parse(raw);
+}
+
+export function writeResult(payload) {
+  process.stdout.write(JSON.stringify(payload));
+}
+
+export function writeFailure(message) {
+  writeResult({ result: 'failure', error: message });
+}

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+
+try {
+  const input = await readStdinJson();
+  const boardDir = String(input.BOARD_DIR ?? '').trim();
+  const cardsGlob = String(input.CARDS_GLOB ?? '').trim();
+
+  if (!boardDir || !cardsGlob) {
+    writeFailure('BOARD_DIR and CARDS_GLOB are required');
+    process.exit(0);
+  }
+
+  runBoardCli(['add-cards', '--rg', boardDir, '--card-glob', cardsGlob]);
+
+  writeResult({
+    result: 'success',
+    data: {
+      board_dir: boardDir,
+      cards_glob: cardsGlob,
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  writeFailure(message);
+}

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

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+
+try {
+  const input = await readStdinJson();
+  const boardDir = String(input.BOARD_DIR ?? '').trim();
+
+  if (!boardDir) {
+    writeFailure('BOARD_DIR is required');
+    process.exit(0);
+  }
+
+  runBoardCli(['init', boardDir]);
+  writeResult({
+    result: 'success',
+    data: {
+      board_dir: boardDir,
+      message: `initialized ${boardDir}`,
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  writeFailure(message);
+}

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

@@ -0,0 +1,29 @@
+#!/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();
+
+  if (!boardDirInput) {
+    writeFailure('BOARD_DIR is required');
+    process.exit(0);
+  }
+
+  const boardDir = path.resolve(boardDirInput);
+  fs.rmSync(boardDir, { recursive: true, force: true });
+
+  writeResult({
+    result: 'success',
+    data: {
+      board_dir: boardDir,
+      reset: true,
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  writeFailure(message);
+}

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+
+try {
+  const input = await readStdinJson();
+  const boardDir = String(input.BOARD_DIR ?? '').trim();
+  const task = String(input.TASK ?? '').trim();
+
+  if (!boardDir || !task) {
+    writeFailure('BOARD_DIR and TASK are required');
+    process.exit(0);
+  }
+
+  runBoardCli(['retrigger', '--rg', boardDir, '--task', task]);
+
+  writeResult({
+    result: 'success',
+    data: {
+      task,
+      retriggered: true,
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  writeFailure(message);
+}

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

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

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

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+
+try {
+  const input = await readStdinJson();
+  const boardDir = String(input.BOARD_DIR ?? '').trim();
+  const cardsDir = String(input.CARDS_DIR ?? '').trim();
+  const holdings = input.HOLDINGS;
+
+  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');
+  const raw = fs.readFileSync(cardPath, 'utf-8');
+  const card = JSON.parse(raw);
+  card.state = card.state ?? {};
+  card.state.holdings = holdings;
+  fs.writeFileSync(cardPath, `${JSON.stringify(card, null, 2)}\n`, 'utf-8');
+
+  runBoardCli(['update-card', '--rg', boardDir, '--card-id', 'portfolio-form', '--restart']);
+
+  writeResult({
+    result: 'success',
+    data: {
+      saved: true,
+      holdings_count: holdings.length,
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  writeFailure(message);
+}

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+try {
+  const input = await readStdinJson();
+  const boardDir = String(input.BOARD_DIR ?? '').trim();
+  const tasks = Array.isArray(input.COMPLETION_TASKS) ? input.COMPLETION_TASKS : [];
+  const label = String(input.LABEL ?? 'WAIT');
+  const timeoutMs = Number(input.TIMEOUT_MS ?? 30000);
+  const pollMs = Number(input.POLL_MS ?? 500);
+
+  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));
+
+    if (complete) {
+      writeResult({
+        result: 'success',
+        data: {
+          label,
+          completed: true,
+        },
+      });
+      process.exit(0);
+    }
+
+    await sleep(pollMs);
+  }
+
+  writeResult({
+    result: 'timeout',
+    data: {
+      label,
+      completed: false,
+      error: `${label}: timed out waiting for completion`,
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  writeFailure(message);
+}

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.0",
+  "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,9 +78,12 @@
     "./stores/file": false
   },
   "files": [
+    "board-live-cards-cli.js",
+    "step-machine-cli.js",
     "dist",
     "schema",
-    "browser"
+    "browser",
+    "examples"
   ],
   "scripts": {
     "build": "tsup",
@@ -89,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": {