yaml-flow 3.1.0 → 4.0.0

package/examples/cli/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/cli/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/cli/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/cli/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/cli/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/cli/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/cli/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/examples/cli/step-machine-demo/jsonata-init-board-cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+let raw = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => {
+  raw += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(raw || '{}');
+    const boardDirFromArg = process.argv[2] ?? '';
+    const boardDirFromInput = 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',
+      }));
+      return;
+    }
+
+    process.stdout.write(JSON.stringify({
+      result: 'success',
+      data: {
+        message: `initialized ${boardDirFromArg}`,
+        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.stdin.resume();

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

@@ -0,0 +1,30 @@
+id: jsonata-init-board-demo
+settings:
+  start_step: t0_init_board
+  max_total_steps: 10
+  timeout_ms: 30000
+
+steps:
+  t0_init_board:
+    description: Build board path with JSONata and invoke CLI with command templating
+    expects_data: [runtime_root, board_name]
+    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
+    transitions:
+      success: success_state
+      failure: failed_state
+
+terminal_states:
+  success_state:
+    return_intent: success
+    return_artifacts: [board_dir, init_message]
+
+  failed_state:
+    return_intent: failure
+    return_artifacts: [error]

package/examples/cli/step-machine-demo/one-step-cli-only.flow.yaml

@@ -0,0 +1,19 @@
+id: one-step-cli-only
+settings:
+  start_step: run_cli
+steps:
+  run_cli:
+    expects_data: [x]
+    produces_data: [y]
+    handler:
+      cli: node ./step-cli-echo-y.js
+    transitions:
+      success: success_state
+      failure: failed_state
+terminal_states:
+  success_state:
+    return_intent: success
+    return_artifacts: [x, y]
+  failed_state:
+    return_intent: failure
+    return_artifacts: [error]

package/examples/cli/step-machine-demo/step-cli-echo-y.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+let raw = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  const input = JSON.parse(raw || '{}');
+  const x = Number(input.x);
+  if (!Number.isFinite(x)) {
+    process.stdout.write(JSON.stringify({ result: 'failure', error: 'x must be numeric' }));
+    return;
+  }
+  process.stdout.write(JSON.stringify({ result: 'success', data: { y: x + 10, z: 999 } }));
+});
+process.stdin.resume();

package/examples/cli/step-machine-demo/step2-double-cli.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+let raw = '';
+
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => {
+  raw += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(raw || '{}');
+    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);
+      return;
+    }
+
+    const d = c * 2;
+    process.stdout.write(JSON.stringify({
+      status: 'success',
+      data: {
+        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.stdin.resume();

package/examples/cli/step-machine-demo/two-step-math-handlers.js

@@ -0,0 +1,32 @@
+export default {
+  async step1_add(input) {
+    const a = Number(input.a);
+    const b = Number(input.b);
+
+    if (!Number.isFinite(a) || !Number.isFinite(b)) {
+      return {
+        result: 'failure',
+        data: { error: 'step1_add requires numeric input a and b' },
+      };
+    }
+
+    const c = a + b;
+    console.log(`[step1_add] a=${a}, b=${b}, c=${c}`);
+    return { result: 'success', data: { a, b, c } };
+  },
+
+  async step2_double(input) {
+    const c = Number(input.c);
+
+    if (!Number.isFinite(c)) {
+      return {
+        result: 'failure',
+        data: { error: 'step2_double requires numeric input c' },
+      };
+    }
+
+    const d = c * 2;
+    console.log(`[step2_double] c=${c}, d=${d}`);
+    return { result: 'success', data: { d } };
+  },
+};

package/examples/cli/step-machine-demo/two-step-math.flow.yaml

@@ -0,0 +1,31 @@
+id: two-step-math
+settings:
+  start_step: step1_add
+  max_total_steps: 10
+  timeout_ms: 10000
+
+steps:
+  step1_add:
+    description: Compute c = a + b
+    expects_data: [a, b]
+    produces_data: [c]
+    transitions:
+      success: step2_double
+      failure: failed_state
+
+  step2_double:
+    description: Compute d = c * 2
+    expects_data: [c]
+    produces_data: [d]
+    transitions:
+      success: success_state
+      failure: failed_state
+
+terminal_states:
+  success_state:
+    return_intent: success
+    return_artifacts: [a, b, c, d]
+
+  failed_state:
+    return_intent: failure
+    return_artifacts: [error]

package/examples/cli/step-machine-demo/two-step-mixed-handlers.js

@@ -0,0 +1,24 @@
+export default {
+  async step1_add(input) {
+    const a = Number(input.a);
+    const b = Number(input.b);
+
+    if (!Number.isFinite(a) || !Number.isFinite(b)) {
+      return {
+        result: 'failure',
+        data: { error: 'step1_add expects numeric a and b' },
+      };
+    }
+
+    const c = a + b;
+
+    return {
+      result: 'success',
+      data: {
+        a,
+        b,
+        c,
+      },
+    };
+  },
+};