yaml-flow 3.1.1 → 5.0.0

package/examples/browser/boards/portfolio-tracker/portfolio-tracker.js

@@ -0,0 +1,217 @@
+/**
+ * portfolio-tracker.js
+ *
+ * Runs the full T0-T4 lifecycle of the portfolio board demo.
+ *
+ * This is a BLACK-BOX client of board-live-cards CLI.
+ * It only calls CLI commands and does NOT inspect board internals.
+ *
+ * Usage:
+ *   node portfolio-tracker.js
+ *   node portfolio-tracker.js --task-executor <path>
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const CARDS_TEMPLATE = path.join(__dirname, 'cards');
+const REPO_ROOT = path.join(__dirname, '..', '..', '..', '..');
+const CLI_WRAPPER = path.join(REPO_ROOT, 'board-live-cards-cli.js');
+const CLI_TS = path.join(REPO_ROOT, 'src', 'cli', 'board-live-cards-cli.ts');
+const CLI_JS = path.join(REPO_ROOT, 'dist', 'cli', 'board-live-cards-cli.js');
+const TSX_CLI = path.join(REPO_ROOT, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+
+// Keep runtime artifacts out of the repository.
+const RUNTIME_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'portfolio-tracker-'));
+const BOARD = path.join(RUNTIME_ROOT, 'board-runtime');
+const CARDS = path.join(RUNTIME_ROOT, 'cards');
+const TMP_FILE = path.join(BOARD, 'tmp_file1');
+
+function parseArgs(argv) {
+  let taskExecutor;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--task-executor') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) {
+        console.error('[ERROR] Missing value for --task-executor');
+        process.exit(1);
+      }
+      taskExecutor = value;
+      i += 1;
+      continue;
+    }
+    console.error(`[ERROR] Unknown argument: ${arg}`);
+    process.exit(1);
+  }
+  return { taskExecutor };
+}
+
+const options = parseArgs(process.argv.slice(2));
+
+console.log(`Runtime root: ${RUNTIME_ROOT}`);
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function cliCommand() {
+  // Prefer node+tsx CLI on Windows to avoid flashing transient cmd windows.
+  if (fs.existsSync(CLI_TS) && fs.existsSync(TSX_CLI)) {
+    return { cmd: process.execPath, prefixArgs: [TSX_CLI, CLI_TS] };
+  }
+  if (fs.existsSync(CLI_WRAPPER)) {
+    return { cmd: process.execPath, prefixArgs: [CLI_WRAPPER] };
+  }
+  if (fs.existsSync(CLI_JS)) {
+    return { cmd: process.execPath, prefixArgs: [CLI_JS] };
+  }
+  return { cmd: process.execPath, prefixArgs: [CLI_WRAPPER] };
+}
+
+function runCli(args, capture = false) {
+  const { cmd, prefixArgs } = cliCommand();
+  const result = spawnSync(cmd, [...prefixArgs, ...args], {
+    stdio: capture ? 'pipe' : 'inherit',
+    shell: false,
+    windowsHide: true,
+    env: {
+      ...process.env,
+      BOARD_LIVE_CARDS_NO_SPAWN: '1',
+    },
+    encoding: capture ? 'utf-8' : undefined,
+  });
+
+  if (result.error) {
+    console.error(`[ERROR] Failed to run CLI ${args[0]}: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  if (result.status !== 0) {
+    if (capture && result.stdout) process.stdout.write(result.stdout);
+    if (capture && result.stderr) process.stderr.write(result.stderr);
+    console.error(`\n[ERROR] board-live-cards-cli ${args[0]} exited with status ${result.status}`);
+    process.exit(1);
+  }
+
+  return capture ? result.stdout : undefined;
+}
+
+function cli(...args) {
+  runCli(args, false);
+}
+
+function statusText() {
+  return runCli(['status', '--rg', BOARD], true) ?? '';
+}
+
+async function waitForAllCompleted(label, timeoutMs = 30000, pollMs = 500) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const out = statusText();
+    const completed = [
+      /\bcompleted\s+portfolio-form\b/.test(out),
+      /\bcompleted\s+price-fetch\b/.test(out),
+      /\bcompleted\s+holdings-table\b/.test(out),
+      /\bcompleted\s+portfolio-value\b/.test(out),
+    ].every(Boolean);
+
+    if (completed) {
+      console.log(`${label}: all cards completed.`);
+      return;
+    }
+
+    await sleep(pollMs);
+  }
+
+  console.error(`[ERROR] ${label}: timed out waiting for all cards to complete.`);
+  console.error(statusText());
+  process.exit(1);
+}
+
+function writePrices(prices) {
+  if (!fs.existsSync(BOARD)) {
+    fs.mkdirSync(BOARD, { recursive: true });
+  }
+  fs.writeFileSync(TMP_FILE, JSON.stringify(prices), 'utf-8');
+  console.log(`Wrote prices: ${JSON.stringify(prices)}`);
+}
+
+function setupRuntimeCards() {
+  fs.rmSync(CARDS, { recursive: true, force: true });
+  fs.mkdirSync(RUNTIME_ROOT, { recursive: true });
+  fs.cpSync(CARDS_TEMPLATE, CARDS, { recursive: true });
+  fs.copyFileSync(path.join(__dirname, 'fetch-prices.js'), path.join(RUNTIME_ROOT, 'fetch-prices.js'));
+}
+
+(async () => {
+  setupRuntimeCards();
+
+  console.log('\n=== T0: Init board ===');
+  fs.rmSync(BOARD, { recursive: true, force: true });
+
+  if (options.taskExecutor) {
+    cli('init', BOARD, '--task-executor', options.taskExecutor);
+  } else {
+    cli('init', BOARD);
+  }
+  cli('add-cards', '--rg', BOARD, '--card-glob', path.join(CARDS, '*.json'));
+
+  console.log('\n--- T0 Status (after add-cards) ---');
+  process.stdout.write(statusText());
+
+  console.log('\n=== T1: Writing market prices ===');
+  writePrices({ AAPL: 198.50, MSFT: 425.30, GOOG: 178.90, AMZN: 192.40, TSLA: 168.75 });
+  await waitForAllCompleted('T1');
+
+  console.log('\n--- T1 Status ---');
+  process.stdout.write(statusText());
+
+  console.log('\n=== T2: Adding GOOG (100 shares) ===');
+  const portfolioFormPath = path.join(CARDS, 'portfolio-form.json');
+  const portfolioFormV2 = {
+    id: 'portfolio-form',
+    meta: { title: 'Portfolio Holdings Form' },
+    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    card_data: {
+      holdings: [
+        { symbol: 'AAPL', qty: 50 },
+        { symbol: 'MSFT', qty: 30 },
+        { symbol: 'GOOG', qty: 100 },
+      ],
+    },
+    view: {
+      elements: [
+        { kind: 'table', label: 'Holdings', data: { bind: 'card_data.holdings', columns: ['symbol', 'qty'] } },
+      ],
+    },
+  };
+  fs.writeFileSync(portfolioFormPath, JSON.stringify(portfolioFormV2, null, 2));
+
+  cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
+  await sleep(500);
+  writePrices({ AAPL: 198.50, MSFT: 425.30, GOOG: 178.90, AMZN: 192.40, TSLA: 168.75 });
+  await waitForAllCompleted('T2');
+
+  console.log('\n--- T2 Status ---');
+  process.stdout.write(statusText());
+
+  console.log('\n=== T3: Force price refresh — AAPL now 205.00 ===');
+  cli('retrigger', '--rg', BOARD, '--task', 'price-fetch');
+  await sleep(500);
+  writePrices({ AAPL: 205.00, MSFT: 425.30, GOOG: 178.90, AMZN: 192.40, TSLA: 168.75 });
+  await waitForAllCompleted('T3');
+
+  console.log('\n--- T3 Status ---');
+  process.stdout.write(statusText());
+
+  console.log('\n=== T4: Final board status ===');
+  process.stdout.write(statusText());
+
+  console.log('\nPortfolio tracker completed successfully');
+})();

package/examples/browser/livecards-browser/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>LiveCards Browser Demo Moved</title>
+  <meta http-equiv="refresh" content="0; url=../../example-board/demo-shell.html" />
+  <style>
+    body {
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #f5f1e8;
+      color: #1f2937;
+      margin: 0;
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      padding: 24px;
+    }
+
+    main {
+      max-width: 680px;
+      background: #fffdf8;
+      border: 1px solid #d6cdbd;
+      border-radius: 16px;
+      padding: 28px;
+      box-shadow: 0 20px 50px rgba(56, 46, 33, 0.08);
+    }
+
+    a {
+      color: #8a3b12;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>LiveCards browser demo moved</h1>
+    <p>The maintained browser demo is now the example-board shell so there is a single LiveCards example path to keep current.</p>
+    <p><a href="../../example-board/demo-shell.html">Open the example-board demo shell</a></p>
+  </main>
+</body>
+</html>

package/examples/browser/{index.html → step-machine-browser/index.html}

@@ -1,58 +1,58 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>yaml-flow Browser Example</title>
-    <style>
-        * { box-sizing: border-box; }
-        body { 
-            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-            max-width: 800px; 
-            margin: 40px auto; 
-            padding: 20px;
-            background: #f5f5f5;
-        }
-        h1 { color: #333; }
-        .card {
-            background: white;
-            border-radius: 8px;
-            padding: 20px;
-            margin: 20px 0;
-            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-        }
-        .step-list {
-            display: flex;
-            gap: 10px;
-            flex-wrap: wrap;
-            margin: 10px 0;
-        }
-        .step {
-            padding: 8px 16px;
-            border-radius: 20px;
-            background: #e0e0e0;
-            font-size: 14px;
-        }
-        .step.active {
-            background: #2196F3;
-            color: white;
-        }
-        .step.completed {
-            background: #4CAF50;
-            color: white;
-        }
-        button {
-            background: #2196F3;
-            color: white;
-            border: none;
-            padding: 12px 24px;
-            border-radius: 6px;
-            cursor: pointer;
-            font-size: 16px;
-            margin: 5px;
-        }
-        button:hover { background: #1976D2; }
-        button:disabled { background: #ccc; cursor: not-allowed; }
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Step Machine Browser Example — yaml-flow</title>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      max-width: 800px;
+      margin: 40px auto;
+      padding: 20px;
+      background: #f5f5f5;
+    }
+    h1 { color: #333; }
+    .card {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      margin: 20px 0;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    }
+    .step-list {
+      display: flex;
+      gap: 10px;
+      flex-wrap: wrap;
+      margin: 10px 0;
+    }
+    .step {
+      padding: 8px 16px;
+      border-radius: 20px;
+      background: #e0e0e0;
+      font-size: 14px;
+    }
+    .step.active {
+      background: #2196F3;
+      color: white;
+    }
+    .step.completed {
+      background: #4CAF50;
+      color: white;
+    }
+    button {
+      background: #2196F3;
+      color: white;
+      border: none;
+      padding: 12px 24px;
+      border-radius: 6px;
+      cursor: pointer;
+      font-size: 16px;
+      margin: 5px;
+    }
+    button:hover { background: #1976D2; }
+    button:disabled { background: #ccc; cursor: not-allowed; }
         .log {
             background: #263238;
             color: #aed581;
@@ -83,7 +83,7 @@
     </style>
 </head>
 <body>
-    <h1>🔄 yaml-flow Browser Demo</h1>
+    <h1>yaml-flow Step Machine Browser Example</h1>
     
     <div class="card">
         <h2>Simple Greeting Flow</h2>

package/examples/cli/step-machine-cli/portfolio-tracker/cards/holdings-table.json

@@ -0,0 +1,22 @@
+{
+  "id": "holdings-table",
+  "meta": { "title": "Holdings Table" },
+  "requires": ["holdings", "prices"],
+  "provides": [{ "bindTo": "table", "src": "computed_values.table" }],
+  "card_data": {},
+  "compute": [
+    {
+      "bindTo": "table",
+      "expr": "{ \"rows\": $map(requires.holdings, function($h) { { \"symbol\": $h.symbol, \"qty\": $h.qty, \"price\": $lookup(requires.prices, $h.symbol), \"value\": $h.qty * $lookup(requires.prices, $h.symbol) } }) }"
+    }
+  ],
+  "view": {
+    "elements": [
+      {
+        "kind": "table",
+        "label": "Portfolio Positions",
+        "data": { "bind": "computed_values.table.rows", "columns": ["symbol", "qty", "price", "value"] }
+      }
+    ]
+  }
+}

package/examples/cli/step-machine-cli/portfolio-tracker/cards/portfolio-form.json

@@ -0,0 +1,43 @@
+{
+  "id": "portfolio-form",
+  "meta": {
+    "title": "Portfolio Holdings Form"
+  },
+  "provides": [
+    {
+      "bindTo": "holdings",
+      "src": "card_data.holdings"
+    }
+  ],
+  "card_data": {
+    "holdings": [
+      {
+        "symbol": "AAPL",
+        "qty": 50
+      },
+      {
+        "symbol": "MSFT",
+        "qty": 30
+      },
+      {
+        "symbol": "GOOG",
+        "qty": 100
+      }
+    ]
+  },
+  "view": {
+    "elements": [
+      {
+        "kind": "table",
+        "label": "Holdings",
+        "data": {
+          "bind": "card_data.holdings",
+          "columns": [
+            "symbol",
+            "qty"
+          ]
+        }
+      }
+    ]
+  }
+}

package/examples/cli/step-machine-cli/portfolio-tracker/cards/portfolio-value.json

@@ -0,0 +1,15 @@
+{
+  "id": "portfolio-value",
+  "meta": { "title": "Portfolio Total Value" },
+  "requires": ["table"],
+  "provides": [{ "bindTo": "totalValue", "src": "computed_values.totalValue" }],
+  "card_data": {},
+  "compute": [
+    { "bindTo": "totalValue", "expr": "$sum(requires.table.rows.value)" }
+  ],
+  "view": {
+    "elements": [
+      { "kind": "metric", "label": "Total Portfolio Value", "data": { "bind": "computed_values.totalValue" } }
+    ]
+  }
+}

package/examples/cli/step-machine-cli/portfolio-tracker/cards/price-fetch.json

@@ -0,0 +1,15 @@
+{
+  "id": "price-fetch",
+  "meta": { "title": "Fetch Market Prices" },
+  "requires": ["holdings"],
+  "provides": [{ "bindTo": "prices", "src": "fetched_sources.prices" }],
+  "card_data": {},
+  "sources": [
+    { "cli": "node ../fetch-prices.js --tmp-file-name tmp_file1", "bindTo": "prices", "outputFile": "prices.json" }
+  ],
+  "view": {
+    "elements": [
+      { "kind": "table", "label": "Market Prices", "data": { "bind": "fetched_sources.prices" } }
+    ]
+  }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * fetch-prices.js
+ * Polls for tmp_file1 payload and outputs JSON to stdout once available.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function getArgValue(flagName) {
+  const idx = process.argv.indexOf(flagName);
+  if (idx < 0) return undefined;
+  return process.argv[idx + 1];
+}
+
+const envBoardDir = (process.env.BOARD_DIR ?? '').trim();
+const tmpFileName = String(getArgValue('--tmp-file-name') ?? process.env.TMP_FILE_NAME ?? 'tmp_file1').trim();
+const tmpFilePath = envBoardDir ? path.join(envBoardDir, tmpFileName) : '';
+
+if (!tmpFilePath) {
+  console.error('BOARD_DIR environment variable is required for fetch-prices.js');
+  process.exit(1);
+}
+
+function getReadableTmpFile() {
+  if (!fs.existsSync(tmpFilePath)) return undefined;
+  const content = fs.readFileSync(tmpFilePath, 'utf-8').trim();
+  if (!content) return undefined;
+  return { tmpFile: tmpFilePath, content };
+}
+
+function waitForFile(timeoutMs = 120000) {
+  const started = Date.now();
+  const interval = setInterval(() => {
+    if (Date.now() - started > timeoutMs) {
+      clearInterval(interval);
+      console.error('Timed out waiting for tmp_file1 market prices input.');
+      process.exit(1);
+    }
+
+    const ready = getReadableTmpFile();
+    if (!ready) return;
+
+    clearInterval(interval);
+    fs.writeFileSync(ready.tmpFile, '', 'utf-8');
+    process.stdout.write(`${ready.content}\n`);
+  }, 250);
+}
+
+waitForFile();

package/examples/cli/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/cli/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/cli/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/cli/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);
+}