yaml-flow 7.0.0 → 7.1.0

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

@@ -164,20 +164,20 @@ function createNodeSpawnInvocationAdapter() {
       if (ref.howToRun !== 'local-node') {
         return { dispatched: false, error: `unsupported howToRun: ${ref.howToRun}` };
       }
-      const whatToRun = String(ref.whatToRun || '');
+      const whatToRun = ref.whatToRun;
       let scriptPath = '';
-      if (whatToRun.startsWith('b64:')) {
+      if (whatToRun && typeof whatToRun === 'object') {
+        if (whatToRun.kind === 'fs-path') scriptPath = whatToRun.value;
+      } else if (typeof whatToRun === 'string' && whatToRun.startsWith('b64:')) {
         try {
           const parsed = parseRef(whatToRun);
           if (parsed.kind === 'fs-path') scriptPath = parsed.value;
         } catch {
           scriptPath = '';
         }
-      } else {
-        scriptPath = whatToRun;
       }
       if (!scriptPath) {
-        return { dispatched: false, error: `no script path in whatToRun: ${whatToRun}` };
+        return { dispatched: false, error: `no fs-path in whatToRun: ${JSON.stringify(whatToRun)}` };
       }
       // Resolve chatsKeyPrefix (blob key prefix) to absolute FS chatDir for handlers
       const finalArgs = { ...args };
@@ -203,17 +203,17 @@ function createNodeSpawnInvocationAdapter() {
     },
     async describe(ref) {
       if (ref.howToRun !== 'local-node') return null;
-      const whatToRun = String(ref.whatToRun || '');
+      const whatToRun = ref.whatToRun;
       let scriptPath = '';
-      if (whatToRun.startsWith('b64:')) {
+      if (whatToRun && typeof whatToRun === 'object') {
+        if (whatToRun.kind === 'fs-path') scriptPath = whatToRun.value;
+      } else if (typeof whatToRun === 'string' && whatToRun.startsWith('b64:')) {
         try {
           const parsed = parseRef(whatToRun);
           if (parsed.kind === 'fs-path') scriptPath = parsed.value;
         } catch {
           scriptPath = '';
         }
-      } else {
-        scriptPath = whatToRun;
       }
       if (!scriptPath) return null;
       try {
@@ -291,9 +291,17 @@ const logger = { info: console.log, warn: console.warn, error: console.error };
 // Track per-board host config for demo-setup (FS paths are host concerns, not runtime concerns)
 const boardHostConfig = new Map();
 
-function buildBoardContextConfig(label, boardDir, cardsDir, taskExecPath, chatHandlerPath, infAdapterPath, boardId) {
+function buildBoardContextConfig(label, boardDir, taskExecPath, chatHandlerPath, infAdapterPath, boardId) {
   fs.mkdirSync(boardDir, { recursive: true });
 
+  // Runtime card store lives inside the board's setup dir, isolated from the source cards dir.
+  // Layout: boardDir/cards/store  — KV card store
+  //         boardDir/cards/chats  — chat blobs
+  //         boardDir/cards/files  — file uploads
+  const runtimeCardsDir = path.join(boardDir, 'cards');
+  const runtimeCardStoreDir = path.join(runtimeCardsDir, 'store');
+  fs.mkdirSync(runtimeCardStoreDir, { recursive: true });
+
   const notifyChannel = `yaml-flow-server-${label}-${boardId}-${process.pid}`;
   const baseRef = parseRef(serializeRef({ kind: 'fs-path', value: boardDir }));
   const boardAdapter = createFsBoardPlatformAdapter(baseRef, YAML_FLOW_CLI_DIR, {
@@ -302,12 +310,11 @@ function buildBoardContextConfig(label, boardDir, cardsDir, taskExecPath, chatHa
   // In the server context the drain loop is driven in-process; suppress the
   // detached CLI spawn that the FS adapter would otherwise fire as a continuation.
   boardAdapter.requestProcessAccumulated = () => {};
-  // Separate artifacts adapter rooted at cardsDir (preserves old FS layout where
-  // chats/files live under cardsDir rather than boardDir)
-  const artifactsRef = parseRef(serializeRef({ kind: 'fs-path', value: cardsDir }));
+  // Artifacts adapter rooted at runtimeCardsDir so chats/ and files/ are siblings of store/.
+  const artifactsRef = parseRef(serializeRef({ kind: 'fs-path', value: runtimeCardsDir }));
   const artifactsAdapter = createFsBoardPlatformAdapter(artifactsRef, YAML_FLOW_CLI_DIR, { suppressSpawn: true });
 
-  const cardStoreRef = serializeRef({ kind: 'fs-path', value: cardsDir });
+  const cardStoreRef = serializeRef({ kind: 'fs-path', value: runtimeCardStoreDir });
 
   return {
     label,
@@ -328,7 +335,8 @@ const runtime = createMultiBoardServerRuntime({
   serverMetaStore,
   logger,
   boardRuntimeFactory: (boardId, entry) => {
-    const cardsDir = typeof entry.cardsDir === 'string' ? path.resolve(entry.cardsDir) : defaultCardsDir;
+    // sourceCardsDir: read-only source used only for initial seeding.
+    const sourceCardsDir = typeof entry.cardsDir === 'string' ? path.resolve(entry.cardsDir) : defaultCardsDir;
     const boardRoot = path.join(setupDir, `board-${boardId}`);
     const boardDir = path.join(boardRoot, 'runtime');
 
@@ -337,29 +345,32 @@ const runtime = createMultiBoardServerRuntime({
     const infAdapterPath = typeof entry.inferenceAdapterPath === 'string' ? entry.inferenceAdapterPath : defaultInferenceAdapterPath;
     const stepMachinePath = typeof entry.stepMachineCliPath === 'string' ? entry.stepMachineCliPath : defaultStepMachineCliPath;
 
-    const gandalfCardsDir_ = typeof entry.gandalfCardsDir === 'string' ? path.resolve(entry.gandalfCardsDir) : defaultGandalfCardsDir;
+    const sourceGandalfCardsDir = typeof entry.gandalfCardsDir === 'string' ? path.resolve(entry.gandalfCardsDir) : defaultGandalfCardsDir;
     const gandalfTaskExecPath = typeof entry.gandalfTaskExecutorPath === 'string' ? entry.gandalfTaskExecutorPath : defaultGandalfTaskExecutorPath;
     const gandalfChatPath = typeof entry.gandalfChatHandlerPath === 'string' ? entry.gandalfChatHandlerPath : defaultGandalfChatHandlerPath;
     const gandalfInfPath = typeof entry.gandalfInferenceAdapterPath === 'string' ? entry.gandalfInferenceAdapterPath : defaultGandalfInferenceAdapterPath;
 
-    const baseCfg = buildBoardContextConfig('base', boardDir, cardsDir, taskExecPath, chatHandlerPath_, infAdapterPath, boardId);
+    const baseCfg = buildBoardContextConfig('base', boardDir, taskExecPath, chatHandlerPath_, infAdapterPath, boardId);
 
     const boards = [baseCfg];
-    if (gandalfCardsDir_ && gandalfTaskExecPath) {
-      const gandalfBoardDir = path.join(boardRoot, 'gandalf-runtime');
-      const gandalfCfg = buildBoardContextConfig('gandalf', gandalfBoardDir, gandalfCardsDir_, gandalfTaskExecPath, gandalfChatPath, gandalfInfPath, boardId);
-      // Fix gandalf outputsStoreRef
+    let gandalfBoardDir = null;
+    if (sourceGandalfCardsDir && gandalfTaskExecPath) {
+      gandalfBoardDir = path.join(boardRoot, 'gandalf-runtime');
+      const gandalfCfg = buildBoardContextConfig('gandalf', gandalfBoardDir, gandalfTaskExecPath, gandalfChatPath, gandalfInfPath, boardId);
       gandalfCfg.outputsStoreRef = serializeRef({ kind: 'fs-path', value: path.join(boardRoot, 'gandalf-runtime-out', '.outputs') });
       boards.push(gandalfCfg);
     }
 
     // Store host config for demo-setup (FS paths are host concerns)
-    boardHostConfig.set(boardId, { cardsDir, gandalfCardsDir: gandalfCardsDir_, boardDir, boardRoot });
+    boardHostConfig.set(boardId, { cardsDir: sourceCardsDir, gandalfCardsDir: sourceGandalfCardsDir, boardDir, boardRoot });
 
     // Auto-run demo-setup (write copilot-instructions.md) at board init time,
     // so clients no longer need a separate /demo-setup request before bootstrapping.
     demoPrepSetup(boardId);
 
+    // runtimeCardsDir is where the live card store lives (inside setupDir).
+    const runtimeCardsDir = path.join(boardDir, 'cards');
+
     const singleBoardRuntime = createSingleBoardServerRuntime({
       apiBasePath: `${apiBasePath}/${boardId}`,
       boardId,
@@ -370,18 +381,30 @@ const runtime = createMultiBoardServerRuntime({
       serverUrl: `http://127.0.0.1:${PORT}`,
       executionExtra: {
         boardSetupRoot: boardRoot,
-        chatsBlobBasePath: path.join(cardsDir, 'chats'),
+        chatsBlobBasePath: path.join(runtimeCardsDir, 'chats'),
         ...(stepMachinePath ? { stepMachineCliPath: stepMachinePath } : {}),
       },
     });
 
-    // Host concern (Part A): seed card store from FS source only if empty
+    // Host concern: seed card store from source cardsDir only if the runtime store is empty.
     const existing = singleBoardRuntime.cardStore.get({});
     const isEmpty = existing.status !== 'success' || !existing.data?.cards?.length;
     if (isEmpty) {
-      const cards = createFsCardSource(cardsDir).listCards();
+      const cards = createFsCardSource(sourceCardsDir).listCards();
       if (cards.length) singleBoardRuntime.cardStore.set({ body: cards });
     }
+    // Seed gandalf board if present
+    if (gandalfBoardDir && sourceGandalfCardsDir) {
+      const gandalfRuntime = singleBoardRuntime.getBoardRuntime?.('gandalf');
+      if (gandalfRuntime) {
+        const gExisting = gandalfRuntime.cardStore.get({});
+        const gEmpty = gExisting.status !== 'success' || !gExisting.data?.cards?.length;
+        if (gEmpty) {
+          const gCards = createFsCardSource(sourceGandalfCardsDir).listCards();
+          if (gCards.length) gandalfRuntime.cardStore.set({ body: gCards });
+        }
+      }
+    }
 
     return singleBoardRuntime;
   },

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

@@ -6,13 +6,13 @@
   <title>Example Board Demo (LocalStorage Runtime)</title>
   <link rel="icon" type="image/svg+xml" href="favicon.svg" />
   <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/yaml-flow@7.0.0/browser/compute-jsonata.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.1.0/browser/compute-jsonata.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/dompurify/dist/purify.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/leader-line/leader-line.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.0.0/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.0.0/browser/board-livecards-localstorage.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.1.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.1.0/browser/board-livecards-localstorage.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">

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

@@ -19,8 +19,8 @@
   <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/dompurify/dist/purify.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/leader-line/leader-line.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.0.0/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.0.0/browser/board-livecards-client.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.1.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.1.0/browser/board-livecards-client.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">

package/examples/example-board/demo-task-executor.js

@@ -265,12 +265,7 @@ async function executeStepMachineSourceFlow(context) {
   const flow = await loadStepFlow(flowPath);
 
   const invokeHttpRef = async (ref, args) => {
-    let rawUrl = ref.whatToRun;
-    try {
-      rawUrl = parseRef(ref.whatToRun).value;
-    } catch {
-      // Keep raw value when whatToRun is already a URL.
-    }
+    const rawUrl = typeof ref.whatToRun === 'object' ? ref.whatToRun.value : parseRef(ref.whatToRun).value;
 
     const base = String(args?.extra?.serverUrl || 'http://127.0.0.1:7799').replace(/\/$/, '');
     const resolvedUrl = /^https?:\/\//i.test(rawUrl)
@@ -326,10 +321,11 @@ async function executeStepMachineSourceFlow(context) {
       return invokeHttpRef(ref, args);
     }
     if (ref.howToRun === 'demo-local-module') {
-      const modulePath = path.resolve(__dirname, ref.whatToRun);
+      const whatValue = typeof ref.whatToRun === 'object' ? ref.whatToRun.value : parseRef(ref.whatToRun).value;
+      const modulePath = path.resolve(__dirname, whatValue);
       const mod = await import(pathToFileURL(modulePath).href);
       if (typeof mod.execute !== 'function') {
-        throw new Error(`Flow module ${ref.whatToRun} must export execute(context)`);
+        throw new Error(`Flow module ${JSON.stringify(ref.whatToRun)} must export execute(context)`);
       }
       return mod.execute(args);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml-flow",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",
@@ -138,7 +138,7 @@
     "build:example": "node demo-src/example-board/build.js",
     "dev": "tsup --watch",
     "test": "npm run build:example && vitest",
-    "test:run": "npm run build:example && vitest run",
+    "test:run": "npm run build && npm run build:example && vitest run",
     "test:cli-parity": "python scripts/cli_parity_check.py",
     "test:cli-parity:full": "python scripts/cli_parity_check.py --include-portfolio",
     "test:e2e": "python examples/browser/boards/portfolio-tracker/portfolio-tracker.py --run-pycli",

package/step-machine-cli.js

@@ -376,7 +376,7 @@ function normalizeExecutionRef(ref) {
     if (!decoded || typeof decoded !== 'object' || typeof decoded.value !== 'string') {
       return ref;
     }
-    return { ...ref, whatToRun: decoded.value };
+    return { ...ref, whatToRun: decoded };
   } catch {
     return ref;
   }

package/examples/example-board/cards/_index.json

@@ -1,47 +0,0 @@
-{
-  "card-portfolio-intelligence": {
-    "key": "card-portfolio-intelligence",
-    "checksum": "card-portfolio-intelligence",
-    "updatedAt": "2026-05-10T09:38:02.181Z"
-  },
-  "card-market-prices": {
-    "key": "card-market-prices",
-    "checksum": "card-market-prices",
-    "updatedAt": "2026-05-10T09:38:02.161Z"
-  },
-  "card-my-identity": {
-    "key": "card-my-identity",
-    "checksum": "card-my-identity",
-    "updatedAt": "2026-05-10T09:38:02.168Z"
-  },
-  "card-portfolio-action": {
-    "key": "card-portfolio-action",
-    "checksum": "card-portfolio-action",
-    "updatedAt": "2026-05-10T09:38:02.174Z"
-  },
-  "card-portfolio-risks": {
-    "key": "card-portfolio-risks",
-    "checksum": "card-portfolio-risks",
-    "updatedAt": "2026-05-10T09:38:02.187Z"
-  },
-  "card-portfolio-value": {
-    "key": "card-portfolio-value",
-    "checksum": "card-portfolio-value",
-    "updatedAt": "2026-05-10T09:38:02.195Z"
-  },
-  "card-portfolio": {
-    "key": "card-portfolio",
-    "checksum": "card-portfolio",
-    "updatedAt": "2026-05-10T09:38:02.201Z"
-  },
-  "card-rebalance-impact": {
-    "key": "card-rebalance-impact",
-    "checksum": "card-rebalance-impact",
-    "updatedAt": "2026-05-10T09:38:02.208Z"
-  },
-  "card-rebalance-sim": {
-    "key": "card-rebalance-sim",
-    "checksum": "card-rebalance-sim",
-    "updatedAt": "2026-05-10T09:38:02.214Z"
-  }
-}