yaml-flow 3.1.1 → 4.0.0

package/examples/{batch → npm-libs/batch}/batch-step-machine.ts

@@ -7,7 +7,7 @@
  *  - Progress tracking
  *  - Mixed success/failure handling
  *
- * Run with: npx tsx examples/batch/batch-step-machine.ts
+ * Run with: npx tsx examples/npm-libs/batch/batch-step-machine.ts
  */
 
 import { batch } from '../../src/batch/index.js';

package/examples/{continuous-event-graph → npm-libs/continuous-event-graph}/live-cards-board.ts

@@ -16,7 +16,7 @@
  *  - LiveBoard overload — board.id, board.settings forwarded to GraphConfig
  *  - validateReactiveGraph on the resulting graph
  *
- * Run with: npx tsx examples/continuous-event-graph/live-cards-board.ts
+ * Run with: npx tsx examples/npm-libs/continuous-event-graph/live-cards-board.ts
  */
 
 import {

package/examples/{continuous-event-graph → npm-libs/continuous-event-graph}/live-portfolio-dashboard.ts

@@ -22,7 +22,7 @@
  * Dynamically added: allocation-chart, risk-score, daily-pnl,
  *   value-alert, summary, correlation, combined-view
  *
- * Run with: npx tsx examples/continuous-event-graph/live-portfolio-dashboard.ts
+ * Run with: npx tsx examples/npm-libs/continuous-event-graph/live-portfolio-dashboard.ts
  */
 
 import * as fs from 'node:fs';

package/examples/{continuous-event-graph → npm-libs/continuous-event-graph}/portfolio-tracker.ts

@@ -29,7 +29,7 @@
  *   T3: Force price refresh without form change → retrigger('price-fetch')
  *   T4: Quiescent
  *
- * Run with: npx tsx examples/continuous-event-graph/portfolio-tracker.ts
+ * Run with: npx tsx examples/npm-libs/continuous-event-graph/portfolio-tracker.ts
  */
 
 import type { GraphConfig } from '../../src/event-graph/types.js';

package/examples/{continuous-event-graph → npm-libs/continuous-event-graph}/reactive-monitoring.ts

@@ -15,7 +15,7 @@
  * Scenario: A monitoring system that collects metrics, evaluates alerts,
  * and dynamically adds notification channels at runtime.
  *
- * Run with: npx tsx examples/continuous-event-graph/reactive-monitoring.ts
+ * Run with: npx tsx examples/npm-libs/continuous-event-graph/reactive-monitoring.ts
  */
 
 import {

package/examples/{continuous-event-graph → npm-libs/continuous-event-graph}/reactive-pipeline.ts

@@ -9,7 +9,7 @@
  *  - validateLiveGraph for runtime state-consistency checks
  *  - validateReactiveGraph for handler/dispatch checks
  *
- * Run with: npx tsx examples/continuous-event-graph/reactive-pipeline.ts
+ * Run with: npx tsx examples/npm-libs/continuous-event-graph/reactive-pipeline.ts
  */
 
 import {

package/examples/{continuous-event-graph → npm-libs/continuous-event-graph}/soc-incident-board.ts

@@ -31,7 +31,7 @@
  *   T1: New intel arrives → retrigger threat-intel → data-changed cascade
  *       create-ticket skipped (once) — slack re-fires
  *
- * Run with: npx tsx examples/continuous-event-graph/soc-incident-board.ts
+ * Run with: npx tsx examples/npm-libs/continuous-event-graph/soc-incident-board.ts
  */
 
 import type { GraphConfig } from '../../src/event-graph/types.js';

package/examples/{continuous-event-graph → npm-libs/continuous-event-graph}/stock-dashboard.ts

@@ -10,7 +10,7 @@
  *  - Scheduling adapts as the graph evolves
  *  - Snapshots allow persistence and restore
  *
- * Run with: npx tsx examples/continuous-event-graph/stock-dashboard.ts
+ * Run with: npx tsx examples/npm-libs/continuous-event-graph/stock-dashboard.ts
  */
 
 import {

package/examples/{event-graph → npm-libs/event-graph}/ci-cd-pipeline.ts

@@ -8,7 +8,7 @@
  *  - Retry configuration
  *  - Stuck detection
  *
- * Run with: npx tsx examples/event-graph/ci-cd-pipeline.ts
+ * Run with: npx tsx examples/npm-libs/event-graph/ci-cd-pipeline.ts
  */
 
 import {

package/examples/{event-graph → npm-libs/event-graph}/executor-diamond.ts

@@ -12,7 +12,7 @@
  *          |
  *        report
  *
- * Run with: npx tsx examples/event-graph/executor-diamond.ts
+ * Run with: npx tsx examples/npm-libs/event-graph/executor-diamond.ts
  */
 
 import {

package/examples/{event-graph → npm-libs/event-graph}/executor-pipeline.ts

@@ -11,7 +11,7 @@
  *
  * Contrast with reactive-pipeline.ts where the graph drives itself.
  *
- * Run with: npx tsx examples/event-graph/executor-pipeline.ts
+ * Run with: npx tsx examples/npm-libs/event-graph/executor-pipeline.ts
  */
 
 import {

package/examples/{event-graph → npm-libs/event-graph}/research-pipeline.ts

@@ -6,7 +6,7 @@
  *  - Goal-based completion
  *  - The standard next() / apply() driver loop
  *
- * Run with: npx tsx examples/event-graph/research-pipeline.ts
+ * Run with: npx tsx examples/npm-libs/event-graph/research-pipeline.ts
  */
 
 import {

package/examples/{graph-of-graphs → npm-libs/graph-of-graphs}/multi-stage-etl.ts

@@ -21,7 +21,7 @@
  * Inner transform flow (step-machine, per record):
  *   parse → validate → normalize → enrich → (accept | reject)
  *
- * Run with: npx tsx examples/graph-of-graphs/multi-stage-etl.ts
+ * Run with: npx tsx examples/npm-libs/graph-of-graphs/multi-stage-etl.ts
  */
 
 import {

package/examples/{graph-of-graphs → npm-libs/graph-of-graphs}/url-processing-pipeline.ts

@@ -19,7 +19,7 @@
  *  - resolveConfigTemplates() for DRY task configs
  *  - Parallel fan-out inside inner graph
  *
- * Run with: npx tsx examples/graph-of-graphs/url-processing-pipeline.ts
+ * Run with: npx tsx examples/npm-libs/graph-of-graphs/url-processing-pipeline.ts
  */
 
 import {

package/examples/{inference → npm-libs/inference}/azure-deployment.ts

@@ -5,7 +5,7 @@
  * The graph has 3 checkpoints. After deployment, the LLM analyzes
  * logs and determines what's complete.
  *
- * Run with: npx tsx examples/inference/azure-deployment.ts
+ * Run with: npx tsx examples/npm-libs/inference/azure-deployment.ts
  */
 
 import {

package/examples/{inference → npm-libs/inference}/copilot-cli.ts

@@ -8,7 +8,7 @@
  *   - GitHub Copilot CLI installed (comes with VS Code / GitHub Copilot extension)
  *   - `copilot` available on PATH
  *
- * Run with: npx tsx examples/inference/copilot-cli.ts
+ * Run with: npx tsx examples/npm-libs/inference/copilot-cli.ts
  */
 
 import { createLiveGraph, schedule } from '../../src/continuous-event-graph/index.js';

package/examples/{inference → npm-libs/inference}/data-pipeline.ts

@@ -4,7 +4,7 @@
  * Demonstrates iterative inference — run the LLM multiple times as
  * new evidence arrives. Each round may unlock more tasks.
  *
- * Run with: npx tsx examples/inference/data-pipeline.ts
+ * Run with: npx tsx examples/npm-libs/inference/data-pipeline.ts
  */
 
 import {

package/examples/{inference → npm-libs/inference}/pluggable-adapters.ts

@@ -4,7 +4,7 @@
  * Shows how to create adapters for different LLM providers.
  * Each adapter implements InferenceAdapter.analyze(prompt) → string.
  *
- * Run with: npx tsx examples/inference/pluggable-adapters.ts
+ * Run with: npx tsx examples/npm-libs/inference/pluggable-adapters.ts
  */
 
 import {

package/examples/{node → npm-libs/node}/ai-conversation.ts

@@ -7,7 +7,7 @@
  * - Circuit breakers
  * - Event handling
  * 
- * Run with: npx ts-node examples/node/ai-conversation.ts
+ * Run with: npx ts-node examples/npm-libs/node/ai-conversation.ts
  */
 
 import { createEngine, loadFlow, MemoryStore } from '../../src/index.js';

package/examples/{node → npm-libs/node}/simple-greeting.ts

@@ -3,8 +3,8 @@
  * 
  * Demonstrates basic usage with file-based persistence.
  * 
- * Run with: npx ts-node examples/node/simple-greeting.ts
- * Or after build: node examples/node/simple-greeting.js
+ * Run with: npx ts-node examples/npm-libs/node/simple-greeting.ts
+ * Or after build: node examples/npm-libs/node/simple-greeting.js
  */
 
 import { createEngine, loadFlow, FileStore } from '../../src/index.js';

package/examples/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" }],
+  "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/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": "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/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" }],
+  "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/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": "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/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/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);
+}