yaml-flow 5.0.0 → 5.1.0

package/examples/example-board/demo-server-config.json

@@ -0,0 +1,7 @@
+{
+  "port": 7799,
+  "boardLiveCardsCliJs": "../../dist/cli/board-live-cards-cli.js",
+  "stepMachineCliPath": "../../step-machine-cli.js",
+  "taskExecutorPath": "./demo-task-executor.js",
+  "chatHandlerPath": "./demo-chat-handler.js"
+}

package/examples/example-board/demo-server.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import http from 'node:http';
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -13,7 +14,40 @@ import {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const PORT = Number(process.env.DEMO_SERVER_PORT || 7799);
+function loadServerConfig() {
+  const configPath = path.join(__dirname, 'demo-server-config.json');
+  if (!fs.existsSync(configPath)) return {};
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function resolveFromConfig(configValue) {
+  if (typeof configValue !== 'string' || !configValue.trim()) return null;
+  return path.resolve(__dirname, configValue);
+}
+
+const serverConfig = loadServerConfig();
+const configuredCliJs = resolveFromConfig(serverConfig.boardLiveCardsCliJs);
+const configuredTaskExecutorPath = resolveFromConfig(serverConfig.taskExecutorPath || serverConfig.demoTaskExecutorPath);
+const configuredStepMachineCliPath = resolveFromConfig(serverConfig.stepMachineCliPath);
+const configuredChatHandlerPath = resolveFromConfig(serverConfig.chatHandlerPath);
+
+if (!process.env.BOARD_LIVE_CARDS_CLI_JS && configuredCliJs) {
+  process.env.BOARD_LIVE_CARDS_CLI_JS = configuredCliJs;
+}
+if (!process.env.DEMO_STEP_MACHINE_CLI_PATH && configuredStepMachineCliPath) {
+  process.env.DEMO_STEP_MACHINE_CLI_PATH = configuredStepMachineCliPath;
+}
+if (!process.env.DEMO_CHAT_HANDLER_PATH && configuredChatHandlerPath) {
+  process.env.DEMO_CHAT_HANDLER_PATH = configuredChatHandlerPath;
+}
+
+const PORT = Number(process.env.DEMO_SERVER_PORT || serverConfig.port || 7799);
 const CORS_HEADERS = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Headers': 'content-type,x-file-name',
@@ -22,7 +56,10 @@ const CORS_HEADERS = {
 
 const runtime = createMultiBoardServerRuntime({
   apiBasePath: '/api/boards',
-  defaultTaskExecutorPath: process.env.DEMO_TASK_EXECUTOR_PATH || path.join(__dirname, 'demo-task-executor.js'),
+  defaultTaskExecutorPath: process.env.DEMO_TASK_EXECUTOR_PATH || configuredTaskExecutorPath || path.join(__dirname, 'demo-task-executor.js'),
+  defaultStepMachineCliPath: process.env.DEMO_STEP_MACHINE_CLI_PATH || configuredStepMachineCliPath,
+  defaultChatHandlerPath: process.env.DEMO_CHAT_HANDLER_PATH || configuredChatHandlerPath || path.join(__dirname, 'demo-chat-handler.js'),
+  boardLiveCardsCliJs: process.env.BOARD_LIVE_CARDS_CLI_JS || configuredCliJs,
 });
 
 const dispatch = createRuntimeRequestDispatcher(runtime);

package/examples/example-board/demo-shell-browser.html

@@ -6,9 +6,9 @@
   <title>Example Board Demo (Browser Runtime)</title>
   <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
   <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
-  <script src="../../browser/card-compute.js" onerror="this.onerror=null;this.src='https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/card-compute.js';"></script>
-  <script src="../../browser/live-cards.js" onerror="this.onerror=null;this.src='https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/live-cards.js';"></script>
-  <script src="../../browser/board-livegraph-runtime.js" onerror="this.onerror=null;this.src='https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/board-livegraph-runtime.js';"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/card-compute.js" onerror="this.onerror=null;this.src='../../browser/card-compute.js';"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/live-cards.js" onerror="this.onerror=null;this.src='../../browser/live-cards.js';"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/board-livegraph-runtime.js" onerror="this.onerror=null;this.src='../../browser/board-livegraph-runtime.js';"></script>
    <script src="./reusable-runtime-artifacts-adapter.js"></script>
 </head>
 <body class="bg-light">

package/examples/example-board/demo-shell-with-server.html

@@ -6,8 +6,8 @@
   <title>Example Board Demo (Server Runtime)</title>
   <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
   <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
-  <script src="../../browser/card-compute.js" onerror="this.onerror=null;this.src='https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/card-compute.js';"></script>
-  <script src="../../browser/live-cards.js" onerror="this.onerror=null;this.src='https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/live-cards.js';"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/card-compute.js" onerror="this.onerror=null;this.src='../../browser/card-compute.js';"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/live-cards.js" onerror="this.onerror=null;this.src='../../browser/live-cards.js';"></script>
   <script src="./reusable-runtime-artifacts-adapter.js"></script>
   <script src="./reusable-board-runtime-client.js"></script>
 </head>

package/examples/example-board/reusable-server-runtime.js

@@ -138,6 +138,12 @@ export function createMultiBoardServerRuntime(options = {}) {
     const defaultTaskExecutorPath = typeof entry.taskExecutorPath === 'string'
       ? entry.taskExecutorPath
       : options.defaultTaskExecutorPath;
+    const defaultStepMachineCliPath = typeof entry.stepMachineCliPath === 'string'
+      ? entry.stepMachineCliPath
+      : options.defaultStepMachineCliPath;
+    const defaultChatHandlerPath = typeof entry.chatHandlerPath === 'string'
+      ? entry.chatHandlerPath
+      : options.defaultChatHandlerPath;
 
     const service = createExampleBoardServerRuntime({
       apiBasePath: `${apiBasePath}/${boardId}`,
@@ -148,6 +154,9 @@ export function createMultiBoardServerRuntime(options = {}) {
       tmpSurfaceDir: path.join(boardRoot, 'surface'),
       runtimeOutDir: path.join(boardRoot, 'runtime-out'),
       defaultTaskExecutorPath,
+      defaultStepMachineCliPath,
+      defaultChatHandlerPath,
+      boardLiveCardsCliJs: options.boardLiveCardsCliJs,
     });
 
     boardServiceCache.set(boardId, service);
@@ -197,6 +206,7 @@ export function createMultiBoardServerRuntime(options = {}) {
       const label = typeof body.label === 'string' && body.label.trim() ? body.label.trim() : id;
       const entry = { id, label };
       if (typeof body.cardsDir === 'string') entry.cardsDir = body.cardsDir;
+      if (typeof body.stepMachineCliPath === 'string') entry.stepMachineCliPath = body.stepMachineCliPath;
       config.boards.push(entry);
       writeBoardsConfig(config);
 
@@ -310,6 +320,24 @@ export function createExampleBoardServerRuntime(options = {}) {
       ? options.defaultTaskExecutorPath
       : path.resolve(process.cwd(), options.defaultTaskExecutorPath))
     : null;
+  const configuredStepMachineCliPath = typeof options.defaultStepMachineCliPath === 'string'
+    && options.defaultStepMachineCliPath.trim()
+    ? (path.isAbsolute(options.defaultStepMachineCliPath)
+      ? options.defaultStepMachineCliPath
+      : path.resolve(process.cwd(), options.defaultStepMachineCliPath))
+    : null;
+  const configuredBoardLiveCardsCliJs = typeof options.boardLiveCardsCliJs === 'string'
+    && options.boardLiveCardsCliJs.trim()
+    ? (path.isAbsolute(options.boardLiveCardsCliJs)
+      ? options.boardLiveCardsCliJs
+      : path.resolve(process.cwd(), options.boardLiveCardsCliJs))
+    : null;
+  const configuredChatHandlerPath = typeof options.defaultChatHandlerPath === 'string'
+    && options.defaultChatHandlerPath.trim()
+    ? (path.isAbsolute(options.defaultChatHandlerPath)
+      ? options.defaultChatHandlerPath
+      : path.resolve(process.cwd(), options.defaultChatHandlerPath))
+    : null;
 
   const statusSnapshotFile = path.join(runtimeOutDir, 'board-livegraph-status.json');
   const boardFile = path.join(boardDir, 'board-graph.json');
@@ -318,6 +346,8 @@ export function createExampleBoardServerRuntime(options = {}) {
   let didDemoSetup = false;
 
   function resolveCliJsPath() {
+    if (configuredBoardLiveCardsCliJs && fs.existsSync(configuredBoardLiveCardsCliJs)) return configuredBoardLiveCardsCliJs;
+
     const envOverride = process.env.BOARD_LIVE_CARDS_CLI_JS;
     if (envOverride && fs.existsSync(envOverride)) return envOverride;
 
@@ -341,6 +371,10 @@ export function createExampleBoardServerRuntime(options = {}) {
 
   const cliJs = resolveCliJsPath();
 
+  if (!process.env.DEMO_STEP_MACHINE_CLI_PATH && configuredStepMachineCliPath && fs.existsSync(configuredStepMachineCliPath)) {
+    process.env.DEMO_STEP_MACHINE_CLI_PATH = configuredStepMachineCliPath;
+  }
+
   function ensureCardStorageDirs(cardId) {
     const safeCardId = String(cardId || '').replace(/[^a-zA-Z0-9_-]/g, '_') || 'unknown-card';
     const cardDir = path.join(tmpCardsDir, safeCardId);
@@ -417,7 +451,7 @@ export function createExampleBoardServerRuntime(options = {}) {
   function ensureBuilt() {
     if (!cliJs || !fs.existsSync(cliJs)) {
       throw new Error(
-        'Unable to locate board-live-cards CLI. Set BOARD_LIVE_CARDS_CLI_JS or install yaml-flow in this project.'
+        'Unable to locate board-live-cards CLI. Set boardLiveCardsCliJs option, BOARD_LIVE_CARDS_CLI_JS, or install yaml-flow in this project.'
       );
     }
   }
@@ -631,29 +665,51 @@ export function createExampleBoardServerRuntime(options = {}) {
     return resolved;
   }
 
-  function initBoard(taskExecutorPathParam) {
+  function resolveChatHandlerPath(chatHandlerPathParam) {
+    const raw = typeof chatHandlerPathParam === 'string' ? chatHandlerPathParam.trim() : '';
+    const resolved = raw
+      ? (path.isAbsolute(raw) ? raw : path.resolve(__dirname, raw))
+      : configuredChatHandlerPath;
+    if (!resolved) return null;
+    if (!fs.existsSync(resolved)) {
+      const err = new Error(`Chat handler script not found: ${resolved}`);
+      err.statusCode = 400;
+      throw err;
+    }
+    return resolved;
+  }
+
+  function initBoard(taskExecutorPathParam, chatHandlerPathParam) {
     fs.mkdirSync(boardDir, { recursive: true });
 
     const taskExecutorPath = resolveTaskExecutorPath(taskExecutorPathParam);
+    const chatHandlerPath = resolveChatHandlerPath(chatHandlerPathParam);
     const taskExecutorCmd = `${shellQuote(process.execPath)} ${shellQuote(taskExecutorPath)}`;
+    const chatHandlerCmd = chatHandlerPath
+      ? `${shellQuote(process.execPath)} ${shellQuote(chatHandlerPath)}`
+      : null;
+
+    const initArgs = ['init', boardDir, '--task-executor', taskExecutorCmd];
+    if (chatHandlerCmd) initArgs.push('--chat-handler', chatHandlerCmd);
+    initArgs.push('--runtime-out', runtimeOutDir);
 
     try {
-      runCli(['init', boardDir, '--task-executor', taskExecutorCmd, '--runtime-out', runtimeOutDir]);
+      runCli(initArgs);
     } catch (err) {
       const msg = String((err && err.message) || err);
       if (!msg.includes('no valid board-graph.json')) throw err;
 
       clearDirContents(boardDir);
       fs.mkdirSync(boardDir, { recursive: true });
-      runCli(['init', boardDir, '--task-executor', taskExecutorCmd, '--runtime-out', runtimeOutDir]);
+      runCli(initArgs);
     }
   }
 
-  function initBoardAndSetup(taskExecutorPathParam) {
+  function initBoardAndSetup(taskExecutorPathParam, chatHandlerPathParam) {
     ensureDemoSetup();
 
     if (!fs.existsSync(boardFile)) {
-      initBoard(taskExecutorPathParam);
+      initBoard(taskExecutorPathParam, chatHandlerPathParam);
     }
 
     const expectedCardsRoot = path.resolve(tmpCardsDir);
@@ -665,7 +721,7 @@ export function createExampleBoardServerRuntime(options = {}) {
 
     if (hasStaleMapping) {
       clearDirContents(boardDir);
-      initBoard(taskExecutorPathParam);
+      initBoard(taskExecutorPathParam, chatHandlerPathParam);
     }
   }
 
@@ -1095,7 +1151,8 @@ export function createExampleBoardServerRuntime(options = {}) {
     try {
       if (method === 'GET' && p === `${apiBasePath}/init-board`) {
         const taskExecutorPathParam = url.searchParams.get('taskExecutorPath') || '';
-        initBoardAndSetup(taskExecutorPathParam);
+        const chatHandlerPathParam = url.searchParams.get('chatHandlerPath') || '';
+        initBoardAndSetup(taskExecutorPathParam, chatHandlerPathParam);
         json(res, 200, buildPublishedRuntimePayload());
         return true;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml-flow",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",