npm - yaml-flow - Versions diffs - 3.1.0 → 4.0.0 - Mend

yaml-flow 3.1.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (149) hide show

package/examples/browser/step-machine-browser/index.html ADDED Viewed

@@ -0,0 +1,367 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <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;
+            padding: 15px;
+            border-radius: 6px;
+            font-family: 'Consolas', monospace;
+            font-size: 13px;
+            max-height: 300px;
+            overflow-y: auto;
+        }
+        .log-entry { margin: 5px 0; }
+        .log-entry.error { color: #ef5350; }
+        .log-entry.transition { color: #64B5F6; }
+        .result {
+            padding: 15px;
+            border-radius: 6px;
+            margin-top: 15px;
+        }
+        .result.success { background: #C8E6C9; }
+        .result.error { background: #FFCDD2; }
+        input {
+            padding: 10px;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            font-size: 16px;
+            width: 200px;
+        }
+    </style>
+</head>
+<body>
+    <h1>yaml-flow Step Machine Browser Example</h1>
+    <div class="card">
+        <h2>Simple Greeting Flow</h2>
+        <p>Enter your name and run the flow to see it in action.</p>
+        <div style="margin: 15px 0;">
+            <input type="text" id="nameInput" placeholder="Enter your name" value="Developer">
+            <button onclick="runFlow()">Run Flow</button>
+            <button onclick="clearLog()">Clear Log</button>
+        </div>
+        <h3>Steps</h3>
+        <div class="step-list" id="stepList">
+            <div class="step" data-step="greet">greet</div>
+            <div class="step" data-step="validate">validate</div>
+            <div class="step" data-step="personalize">personalize</div>
+            <div class="step" data-step="success_state">✓ success</div>
+        </div>
+    </div>
+    <div class="card">
+        <h3>Execution Log</h3>
+        <div class="log" id="log"></div>
+        <div id="result"></div>
+    </div>
+    <script type="module">
+        // Import from CDN (in production) or local build
+        // For this demo, we'll inline a simplified version
+        // ============= Inline yaml-flow (simplified for demo) =============
+        class MemoryStore {
+            constructor() {
+                this.runs = new Map();
+                this.data = new Map();
+            }
+            async saveRunState(runId, state) { this.runs.set(runId, {...state}); }
+            async loadRunState(runId) { return this.runs.get(runId) || null; }
+            async deleteRunState(runId) { this.runs.delete(runId); this.data.delete(runId); }
+            async setData(runId, key, value) {
+                if (!this.data.has(runId)) this.data.set(runId, {});
+                this.data.get(runId)[key] = value;
+            }
+            async getData(runId, key) { return this.data.get(runId)?.[key]; }
+            async getAllData(runId) { return {...(this.data.get(runId) || {})}; }
+            async clearData(runId) { this.data.delete(runId); }
+        }
+        class FlowEngine {
+            constructor(flow, handlers, options = {}) {
+                this.flow = flow;
+                this.handlers = handlers;
+                this.store = options.store || new MemoryStore();
+                this.components = options.components || {};
+                this.options = options;
+            }
+            async run(initialData = {}) {
+                const runId = crypto.randomUUID();
+                const startedAt = Date.now();
+                const runState = {
+                    runId,
+                    currentStep: this.flow.settings.start_step,
+                    status: 'running',
+                    stepHistory: [],
+                    iterationCounts: {},
+                    retryCounts: {},
+                    startedAt,
+                    updatedAt: startedAt,
+                };
+                await this.store.saveRunState(runId, runState);
+                for (const [key, value] of Object.entries(initialData)) {
+                    await this.store.setData(runId, key, value);
+                }
+                let iterations = 0;
+                const maxSteps = this.flow.settings.max_total_steps || 100;
+                while (iterations < maxSteps) {
+                    const currentStep = runState.currentStep;
+                    // Check terminal state
+                    const terminalState = this.flow.terminal_states[currentStep];
+                    if (terminalState) {
+                        const allData = await this.store.getAllData(runId);
+                        return {
+                            runId,
+                            status: 'completed',
+                            intent: terminalState.return_intent,
+                            data: this.extractReturnData(terminalState.return_artifacts, allData),
+                            finalStep: currentStep,
+                            stepHistory: runState.stepHistory,
+                            durationMs: Date.now() - startedAt,
+                        };
+                    }
+                    const stepConfig = this.flow.steps[currentStep];
+                    const handler = this.handlers[currentStep];
+                    // Build input
+                    const allData = await this.store.getAllData(runId);
+                    const input = stepConfig.expects_data
+                        ? Object.fromEntries(stepConfig.expects_data.map(k => [k, allData[k]]))
+                        : allData;
+                    // Execute
+                    this.options.onStep?.(currentStep, 'start');
+                    const result = await handler(input, { runId, stepName: currentStep, components: this.components, store: this.store });
+                    this.options.onStep?.(currentStep, result.result);
+                    // Store output
+                    if (result.data) {
+                        for (const [key, value] of Object.entries(result.data)) {
+                            await this.store.setData(runId, key, value);
+                        }
+                    }
+                    // Transition
+                    const nextStep = stepConfig.transitions[result.result];
+                    this.options.onTransition?.(currentStep, nextStep);
+                    runState.stepHistory.push(currentStep);
+                    runState.currentStep = nextStep;
+                    iterations++;
+                }
+                return { runId, status: 'max_iterations', data: {}, stepHistory: runState.stepHistory };
+            }
+            extractReturnData(artifacts, allData) {
+                if (!artifacts || artifacts === false) return {};
+                if (typeof artifacts === 'string') return { [artifacts]: allData[artifacts] };
+                if (Array.isArray(artifacts)) return Object.fromEntries(artifacts.map(k => [k, allData[k]]));
+                return allData;
+            }
+        }
+        // ============= Flow Definition =============
+        const flow = {
+            settings: {
+                start_step: 'greet',
+                max_total_steps: 10
+            },
+            steps: {
+                greet: {
+                    produces_data: ['greeting', 'user_name'],
+                    transitions: { success: 'validate', failure: 'error_state' }
+                },
+                validate: {
+                    expects_data: ['greeting', 'user_name'],
+                    produces_data: ['is_valid'],
+                    transitions: { success: 'personalize', invalid: 'error_state', failure: 'error_state' }
+                },
+                personalize: {
+                    expects_data: ['greeting', 'user_name'],
+                    produces_data: ['final_message'],
+                    transitions: { success: 'success_state', failure: 'error_state' }
+                }
+            },
+            terminal_states: {
+                success_state: { return_intent: 'success', return_artifacts: ['final_message', 'user_name'] },
+                error_state: { return_intent: 'error', return_artifacts: false }
+            }
+        };
+        // ============= Step Handlers =============
+        const handlers = {
+            async greet(input) {
+                const userName = input.initial_name || 'World';
+                await sleep(300); // Simulate async work
+                return {
+                    result: 'success',
+                    data: { greeting: 'Hello', user_name: userName }
+                };
+            },
+            async validate(input) {
+                const { greeting, user_name } = input;
+                await sleep(200);
+                const isValid = greeting && user_name;
+                return {
+                    result: isValid ? 'success' : 'invalid',
+                    data: { is_valid: isValid }
+                };
+            },
+            async personalize(input) {
+                const { greeting, user_name } = input;
+                await sleep(200);
+                return {
+                    result: 'success',
+                    data: { final_message: `${greeting}, ${user_name}! Welcome to yaml-flow in the browser! 🎉` }
+                };
+            }
+        };
+        function sleep(ms) {
+            return new Promise(resolve => setTimeout(resolve, ms));
+        }
+        // ============= UI Functions =============
+        const logEl = document.getElementById('log');
+        const resultEl = document.getElementById('result');
+        const stepEls = document.querySelectorAll('.step');
+        function log(message, type = '') {
+            const entry = document.createElement('div');
+            entry.className = `log-entry ${type}`;
+            entry.textContent = `[${new Date().toLocaleTimeString()}] ${message}`;
+            logEl.appendChild(entry);
+            logEl.scrollTop = logEl.scrollHeight;
+        }
+        function updateStep(stepName, status) {
+            stepEls.forEach(el => {
+                if (el.dataset.step === stepName) {
+                    el.classList.remove('active', 'completed');
+                    el.classList.add(status);
+                }
+            });
+        }
+        function resetSteps() {
+            stepEls.forEach(el => el.classList.remove('active', 'completed'));
+        }
+        window.clearLog = function() {
+            logEl.innerHTML = '';
+            resultEl.innerHTML = '';
+            resetSteps();
+        };
+        window.runFlow = async function() {
+            resetSteps();
+            resultEl.innerHTML = '';
+            const name = document.getElementById('nameInput').value || 'World';
+            log(`Starting flow with name: "${name}"`);
+            const engine = new FlowEngine(flow, handlers, {
+                store: new MemoryStore(),
+                onStep: (step, status) => {
+                    log(`Step [${step}]: ${status}`);
+                    updateStep(step, status === 'start' ? 'active' : 'completed');
+                },
+                onTransition: (from, to) => {
+                    log(`Transition: ${from} → ${to}`, 'transition');
+                }
+            });
+            try {
+                const result = await engine.run({ initial_name: name });
+                log(`Flow completed: ${result.intent}`);
+                updateStep(result.finalStep, 'completed');
+                resultEl.innerHTML = `
+                    <div class="result ${result.intent === 'success' ? 'success' : 'error'}">
+                        <strong>Result:</strong> ${result.intent}<br>
+                        <strong>Message:</strong> ${result.data.final_message || 'N/A'}<br>
+                        <strong>Duration:</strong> ${result.durationMs}ms<br>
+                        <strong>Steps:</strong> ${result.stepHistory.join(' → ')} → ${result.finalStep}
+                    </div>
+                `;
+            } catch (error) {
+                log(`Error: ${error.message}`, 'error');
+                resultEl.innerHTML = `<div class="result error">Error: ${error.message}</div>`;
+            }
+        };
+        log('yaml-flow browser demo loaded. Click "Run Flow" to start.');
+    </script>
+</body>
+</html>

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

@@ -0,0 +1,22 @@
+{
+  "id": "holdings-table",
+  "meta": { "title": "Holdings Table" },
+  "requires": ["holdings", "prices"],
+  "provides": [{ "bindTo": "table", "src": "computed_values.table" }],
+  "state": {},
+  "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 ADDED Viewed

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

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

@@ -0,0 +1,15 @@
+{
+  "id": "portfolio-value",
+  "meta": { "title": "Portfolio Total Value" },
+  "requires": ["table"],
+  "provides": [{ "bindTo": "totalValue", "src": "computed_values.totalValue" }],
+  "state": {},
+  "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 ADDED Viewed

@@ -0,0 +1,15 @@
+{
+  "id": "price-fetch",
+  "meta": { "title": "Fetch Market Prices" },
+  "requires": ["holdings"],
+  "provides": [{ "bindTo": "prices", "src": "sources.prices" }],
+  "state": {},
+  "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": "sources.prices" } }
+    ]
+  }
+}

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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/cli/step-machine-cli/portfolio-tracker/handlers/retrigger-cli.js ADDED Viewed

@@ -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);
+}