yaml-flow 3.1.1 → 5.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-task-executor.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Portfolio Tracker Task-Executor
+ * 
+ * Implements the run-source-fetch protocol for board-live-cards.
+ * This script acts as an external task-executor that can be registered via .task-executor file.
+ * 
+ * Contract:
+ *   portfolio-tracker-task-executor.js run-source-fetch --in <defFile> --out <resultFile> --err <errFile>
+ * 
+ * Input (--in file):
+ *   JSON source definition with { cli: "...", bindTo: "...", outputFile: "...", ... }
+ * 
+ * Output (on success):
+ *   --out file contains the execution result
+ *   Exit code: 0
+ * 
+ * Output (on error):
+ *   --err file contains error message
+ *   Exit code: 1
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+let subcommand = '';
+let inFile = '';
+let outFile = '';
+let errFile = '';
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === 'run-source-fetch') {
+    subcommand = 'run-source-fetch';
+  } else if (args[i] === '--in' && i + 1 < args.length) {
+    inFile = args[i + 1];
+  } else if (args[i] === '--out' && i + 1 < args.length) {
+    outFile = args[i + 1];
+  } else if (args[i] === '--err' && i + 1 < args.length) {
+    errFile = args[i + 1];
+  }
+}
+
+if (subcommand !== 'run-source-fetch' || !inFile || !outFile || !errFile) {
+  console.error('Usage: portfolio-tracker-task-executor.js run-source-fetch --in <defFile> --out <resultFile> --err <errFile>');
+  process.exit(1);
+}
+
+try {
+  // 1. Read source definition from --in file
+  console.log(`[portfolio-tracker-task-executor] Reading source definition from ${inFile}`);
+  const sourceDefStr = fs.readFileSync(inFile, 'utf-8');
+  const sourceDef = JSON.parse(sourceDefStr);
+  
+  // 2. Extract cli command from source definition
+  const { cli: sourceCliCommand } = sourceDef;
+  if (!sourceCliCommand) {
+    throw new Error('cli is required in source definition');
+  }
+  
+  console.log(`[portfolio-tracker-task-executor] Executing: ${sourceCliCommand}`);
+  
+  // 3. Execute source.cli synchronously and capture output
+  let output;
+  try {
+    output = execSync(sourceCliCommand, {
+      encoding: 'utf-8',
+      timeout: (sourceDef.timeout ?? 120) * 1000,  // Convert to ms
+      cwd: sourceDef.cwd,
+      shell: true,
+      stdio: ['pipe', 'pipe', 'pipe'],  // Capture stdout/stderr
+    });
+  } catch (execErr) {
+    // Even on error, try to use what output we got
+    output = execErr.stdout || '';
+    if (!output) {
+      throw new Error(`Command execution failed: ${execErr.message}`);
+    }
+  }
+  
+  // 4. Write output to --out file
+  console.log(`[portfolio-tracker-task-executor] Writing result to ${outFile}`);
+  fs.writeFileSync(outFile, output.trim(), 'utf-8');
+  
+  console.log(`[portfolio-tracker-task-executor] Success`);
+  process.exit(0);
+} catch (error) {
+  // 3a. On error: write error message to --err file and exit non-zero
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  console.error(`[portfolio-tracker-task-executor] Error:`, errorMsg);
+  
+  fs.writeFileSync(errFile, errorMsg, 'utf-8');
+  process.exit(1);
+}

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
+  }
+}