yaml-flow 5.2.6 → 5.3.0

package/examples/example-board/cards/card-rebalance-impact.json

@@ -0,0 +1,65 @@
+{
+  "id": "card-rebalance-impact",
+  "meta": {
+    "title": "Rebalance Impact",
+    "tags": ["portfolio", "simulation"],
+    "simulation": true,
+    "desc": "Before/after impact summary of the proposed rebalance scenario."
+  },
+  "requires": ["positions", "proposed_trades"],
+  "compute": [
+    {
+      "bindTo": "total_current_value",
+      "expr": "$round($sum(requires.positions.value), 2)"
+    },
+    {
+      "bindTo": "trade_count",
+      "expr": "$count(requires.proposed_trades)"
+    },
+    {
+      "bindTo": "total_trade_value",
+      "expr": "$round($sum(requires.proposed_trades.trade_value), 2)"
+    },
+    {
+      "bindTo": "buys",
+      "expr": "$count($filter(requires.proposed_trades, function($t){ $t.direction = 'increase' }))"
+    },
+    {
+      "bindTo": "sells",
+      "expr": "$count($filter(requires.proposed_trades, function($t){ $t.direction = 'reduce' }))"
+    },
+    {
+      "bindTo": "max_weight_before",
+      "expr": "($tv := $sum(requires.positions.value); $round($max(requires.positions.value) / $tv * 100, 1))"
+    },
+    {
+      "bindTo": "post_positions",
+      "expr": "($tMap := $merge(requires.proposed_trades.{ticker: $}); $map(requires.positions, function($p) { ($t := $lookup($tMap, $p.ticker); $newQty := $t ? $t.proposed_qty : $p.quantity; {\"ticker\": $p.ticker, \"value\": $round($newQty * $p.price, 2)}) }))"
+    },
+    {
+      "bindTo": "max_weight_after",
+      "expr": "($tv := $sum(computed_values.post_positions.value); $round($max(computed_values.post_positions.value) / $tv * 100, 1))"
+    },
+    {
+      "bindTo": "est_tax_impact",
+      "expr": "$round($sum($filter(requires.proposed_trades, function($t){ $t.direction = 'reduce' }).trade_value) * 0.15, 2)"
+    },
+    {
+      "bindTo": "summary_md",
+      "expr": "'| Metric | Before | After |\\n|---|---|---|\\n| Top holding weight | ' & $string(computed_values.max_weight_before) & '% | ' & $string(computed_values.max_weight_after) & '% |\\n| Portfolio value | $' & $string(computed_values.total_current_value) & ' | ~$' & $string($round(computed_values.total_current_value - computed_values.est_tax_impact, 2)) & ' |\\n\\n**Trades:** ' & $string(computed_values.trade_count) & ' (' & $string(computed_values.buys) & ' buys, ' & $string(computed_values.sells) & ' sells)  \\n**Total trade value:** $' & $string(computed_values.total_trade_value) & '  \\n**Est. tax impact:** ~$' & $string(computed_values.est_tax_impact)"
+    }
+  ],
+  "view": {
+    "elements": [
+      {
+        "kind": "markdown",
+        "data": { "bind": "computed_values.summary_md" }
+      }
+    ],
+    "layout": {
+      "board": { "col": 6, "order": 8 },
+      "canvas": { "x": 1360, "y": 480, "w": 400, "h": 280 }
+    }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-rebalance-sim.json

@@ -0,0 +1,67 @@
+{
+  "id": "card-rebalance-sim",
+  "meta": {
+    "title": "Rebalance Proposal",
+    "tags": ["portfolio", "simulation"],
+    "simulation": true,
+    "desc": "AI-proposed rebalance trades based on portfolio intelligence. Edit quantities before pinning."
+  },
+  "requires": ["holdings", "portfolio_mix", "portfolio_risks", "portfolio_action", "positions"],
+  "source_defs": [
+    {
+      "bindTo": "rebalance",
+      "outputFile": "card-rebalance-proposal.json",
+      "projections": {
+        "holdings": "requires.holdings",
+        "positions": "requires.positions",
+        "portfolio_mix": "requires.portfolio_mix",
+        "portfolio_risks": "requires.portfolio_risks",
+        "portfolio_action": "requires.portfolio_action"
+      },
+      "copilot": {
+        "prompt_template": "You are a portfolio rebalance advisor. Using the intelligence analysis and current holdings below, propose specific trades.\n\nCurrent holdings:\n{{holdings}}\nFields: ticker, quantity, cost_basis ($).\n\nPositions (with live prices):\n{{positions}}\nFields: ticker, quantity, cost_basis, price ($), value ($), gain_$, gain_%, chg_$, chg_pct.\n\nPortfolio intelligence:\n- Mix: {{portfolio_mix}}\n- Risks: {{portfolio_risks}}\n- Action signal: {{portfolio_action}}\n\n{{view_kind_guidance}}\n\n{{card_layout_guidance}}\n\nIMPORTANT OUTPUT RULES:\n- Return ONLY a valid JSON object. No markdown, no preamble, no trailing text.\n- Start with { and end with }.\n- proposed_trades must be an array of objects with EXACTLY these fields per entry:\n  ticker (string), direction (\"reduce\" or \"increase\"), current_qty (number, current shares held), change (number, shares to trade), proposed_qty (number, resulting shares after trade), price (number, current price per share), trade_value (number, change * price rounded to 2 decimals), reason (string, one short sentence).\n- Include one entry per ticker you recommend changing. Do not include tickers with no change.\n- Include a top-level _view object for a ref element with this shape:\n  { \"kind\": \"editable-table\"|\"table\"|\"chart\", \"data\": { ... } }\n- If kind is editable-table or table, include data.columns with the exact proposed_trades fields in desired order.\n- If kind is editable-table, also include data.writeTo = \"card_data.proposed_trades\".\n- If kind is chart, include data.chartType and data.columns as [\"ticker\", \"trade_value\"].\n- If unsure, choose editable-table.\n\n{\n  \"proposed_trades\": [\n    {\"ticker\": \"AAPL\", \"direction\": \"reduce\", \"current_qty\": 15, \"change\": 5, \"proposed_qty\": 10, \"price\": 210.50, \"trade_value\": 1052.50, \"reason\": \"overweight at 41%, trim before earnings\"}\n  ],\n  \"_view\": {\n    \"kind\": \"editable-table\",\n    \"data\": {\n      \"writeTo\": \"card_data.proposed_trades\",\n      \"columns\": [\"ticker\", \"direction\", \"current_qty\", \"change\", \"proposed_qty\", \"price\", \"trade_value\", \"reason\"]\n    }\n  }\n}"
+      }
+    }
+  ],
+  "provides": [
+    { "bindTo": "proposed_trades", "ref": "fetched_sources.rebalance.proposed_trades" }
+  ],
+  "view": {
+    "elements": [
+      {
+        "kind": "ref",
+        "label": "Proposed Trades",
+        "data": {
+          "bind": "fetched_sources.rebalance.proposed_trades",
+          "viewBind": "fetched_sources.rebalance._view",
+          "fallbackKind": "editable-table",
+          "writeTo": "card_data.proposed_trades",
+          "columns": ["ticker", "direction", "current_qty", "change", "proposed_qty", "price", "trade_value", "reason"],
+          "schema": {
+            "properties": {
+              "current_qty": { "type": "number" },
+              "change": { "type": "number" },
+              "proposed_qty": { "type": "number" },
+              "price": { "type": "number" },
+              "trade_value": { "type": "number" }
+            }
+          }
+        }
+      },
+      {
+        "kind": "notes",
+        "label": "Notes",
+        "data": {
+          "bind": "card_data.notes",
+          "writeTo": "card_data.notes"
+        }
+      }
+    ],
+    "layout": {
+      "board": { "col": 6, "order": 7 },
+      "canvas": { "x": 840, "y": 480, "w": 500, "h": 280 }
+    },
+    "features": { "refresh": true }
+  },
+  "card_data": {}
+}

package/examples/example-board/demo-chat-handler.js

@@ -11,6 +11,7 @@
  *   cardsDir        — relative subdir: 'surface/tmp-cards'
  *   chatDir         — absolute path to the card's chats directory
  *   lastChatFile    — filename of the just-written user message, e.g. '001_user.txt'
+ *   serverUrl       — base URL of hosting server (e.g. http://127.0.0.1:7799), optional
  *
  * Invokes copilot_wrapper.bat with a prompt built from conversation history.
  * Session dir is per-card: os.tmpdir()/demo-chat-handler-sessions/<boardId>_<cardId>
@@ -42,7 +43,7 @@ let extra = {};
 try { extra = JSON.parse(Buffer.from(extraStr, 'base64').toString('utf-8')); }
 catch { console.error('[demo-chat-handler] bad --extraEncJson'); process.exit(0); }
 
-const { boardSetupRoot, boardRuntimeDir, runtimeStatusDir, cardsDir, chatDir, lastChatFile } = extra;
+const { boardSetupRoot, boardRuntimeDir, runtimeStatusDir, cardsDir, chatDir, lastChatFile, serverUrl } = extra;
 if (!boardSetupRoot || !chatDir || !lastChatFile) {
   console.error('[demo-chat-handler] missing boardSetupRoot/chatDir/lastChatFile');
   process.exit(0);

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

@@ -1,5 +1,10 @@
 {
   "port": 7799,
+  "cardsDir": "./cards",
   "taskExecutorPath": "./demo-task-executor.js",
-  "chatHandlerPath": "./demo-chat-handler.js"
+  "chatHandlerPath": "./demo-chat-handler.js",
+  "chatSessionsDir": "",
+  "gandalfCardsDir": "./gandalf-cards",
+  "gandalfTaskExecutorPath": "./demo-task-executor.js",
+  "gandalfChatHandlerPath": "./demo-chat-handler.js"
 }

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

@@ -4,6 +4,7 @@ import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { spawnSync, spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 
@@ -48,10 +49,15 @@ function resolveFromConfig(configValue) {
 
 const serverConfig = loadServerConfig();
 const configuredCliJs = resolveFromConfig(serverConfig.boardLiveCardsCliJs) || _pkgCliJs;
+const configuredCardsDir = resolveFromConfig(serverConfig.cardsDir);
 const configuredTaskExecutorPath = resolveFromConfig(serverConfig.taskExecutorPath || serverConfig.demoTaskExecutorPath);
 const configuredStepMachineCliPath = resolveFromConfig(serverConfig.stepMachineCliPath) || _pkgStepMachineCli;
 const configuredChatHandlerPath = resolveFromConfig(serverConfig.chatHandlerPath);
 const configuredInferenceAdapterPath = resolveFromConfig(serverConfig.inferenceAdapterPath);
+const configuredGandalfCardsDir = resolveFromConfig(serverConfig.gandalfCardsDir);
+const configuredGandalfTaskExecutorPath = resolveFromConfig(serverConfig.gandalfTaskExecutorPath);
+const configuredGandalfChatHandlerPath = resolveFromConfig(serverConfig.gandalfChatHandlerPath);
+const configuredGandalfInferenceAdapterPath = resolveFromConfig(serverConfig.gandalfInferenceAdapterPath);
 
 if (!process.env.BOARD_LIVE_CARDS_CLI_JS && configuredCliJs) {
   process.env.BOARD_LIVE_CARDS_CLI_JS = configuredCliJs;
@@ -77,11 +83,16 @@ const CORS_HEADERS = {
 
 const runtime = createMultiBoardServerRuntime({
   apiBasePath: '/api/boards',
-  defaultCardsDir: path.join(__dirname, 'cards'),
-  defaultTaskExecutorPath: process.env.DEMO_TASK_EXECUTOR_PATH || configuredTaskExecutorPath || path.join(__dirname, 'demo-task-executor.js'),
+  serverUrl: `http://127.0.0.1:${PORT}`,
+  defaultCardsDir: process.env.DEMO_CARDS_DIR || configuredCardsDir || null,
+  defaultTaskExecutorPath: process.env.DEMO_TASK_EXECUTOR_PATH || configuredTaskExecutorPath || null,
   defaultStepMachineCliPath: process.env.DEMO_STEP_MACHINE_CLI_PATH || configuredStepMachineCliPath,
-  defaultChatHandlerPath: process.env.DEMO_CHAT_HANDLER_PATH || configuredChatHandlerPath || path.join(__dirname, 'demo-chat-handler.js'),
+  defaultChatHandlerPath: process.env.DEMO_CHAT_HANDLER_PATH || configuredChatHandlerPath || null,
   defaultInferenceAdapterPath: process.env.DEMO_INFERENCE_ADAPTER_PATH || configuredInferenceAdapterPath || null,
+  defaultGandalfCardsDir: process.env.DEMO_GANDALF_CARDS_DIR || configuredGandalfCardsDir || null,
+  defaultGandalfTaskExecutorPath: process.env.DEMO_GANDALF_TASK_EXECUTOR_PATH || configuredGandalfTaskExecutorPath || null,
+  defaultGandalfChatHandlerPath: process.env.DEMO_GANDALF_CHAT_HANDLER_PATH || configuredGandalfChatHandlerPath || null,
+  defaultGandalfInferenceAdapterPath: process.env.DEMO_GANDALF_INFERENCE_ADAPTER_PATH || configuredGandalfInferenceAdapterPath || null,
   boardLiveCardsCliJs: process.env.BOARD_LIVE_CARDS_CLI_JS || configuredCliJs,
 });
 
@@ -91,10 +102,12 @@ function resetRuntime() {
     fs.rmSync(setupDir, { recursive: true, force: true });
     console.log(`[demo-server] reset: wiped ${setupDir}`);
   }
-  const chatSessions = path.join(os.tmpdir(), 'demo-chat-handler-sessions');
-  if (fs.existsSync(chatSessions)) {
-    fs.rmSync(chatSessions, { recursive: true, force: true });
-    console.log(`[demo-server] reset: wiped ${chatSessions}`);
+  const chatSessionsDir = serverConfig.chatSessionsDir
+    ? path.resolve(__dirname, serverConfig.chatSessionsDir)
+    : path.join(os.tmpdir(), 'demo-chat-handler-sessions');
+  if (fs.existsSync(chatSessionsDir)) {
+    fs.rmSync(chatSessionsDir, { recursive: true, force: true });
+    console.log(`[demo-server] reset: wiped ${chatSessionsDir}`);
   }
 }
 
@@ -118,7 +131,7 @@ async function handleDemoSetup(req, res, boardId) {
     const { service, boardRoot } = runtime.requireBoardService(boardId);
     let setupPerformed = false;
 
-    if (!fs.existsSync(path.join(boardRoot, 'surface', 'tmp-cards'))) {
+    if (!service.isDemoSetupDone()) {
       service.ensureDemoSetup();
       setupPerformed = true;
     }
@@ -129,6 +142,69 @@ async function handleDemoSetup(req, res, boardId) {
   }
 }
 
+async function handleWorkiqAsk(req, res) {
+  let body = '';
+  for await (const chunk of req) body += chunk;
+  let query;
+  try {
+    query = JSON.parse(body).query;
+  } catch {
+    return jsonReply(res, 400, { error: 'Invalid JSON body' });
+  }
+  if (!query || typeof query !== 'string') {
+    return jsonReply(res, 400, { error: '{ query } string is required' });
+  }
+
+  const workiqJs = path.join(
+    process.env.APPDATA || os.homedir(),
+    'npm', 'node_modules', '@microsoft', 'workiq', 'bin', 'workiq.js'
+  );
+  if (!fs.existsSync(workiqJs)) {
+    return jsonReply(res, 503, { error: `WorkIQ CLI not found at: ${workiqJs}` });
+  }
+
+  // Server has TTY on stdin — workiq can produce output.
+  // Use async spawn (not spawnSync) to avoid blocking the event loop during the call.
+  await new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let responded = false;
+    const child = spawn(process.execPath, [workiqJs, 'ask', '-q', query], {
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.on('error', (err) => {
+      if (!responded) {
+        responded = true;
+        clearTimeout(timeoutId);
+        jsonReply(res, 500, { error: `workiq spawn error: ${err.message}` });
+      }
+      resolve();
+    });
+    child.on('close', (code) => {
+      if (!responded) {
+        responded = true;
+        clearTimeout(timeoutId);
+        if (code !== 0) {
+          jsonReply(res, 500, { error: `workiq exited ${code}`, stderr });
+        } else {
+          jsonReply(res, 200, { response: stdout });
+        }
+      }
+      resolve();
+    });
+    const timeoutId = setTimeout(() => {
+      if (!responded) {
+        responded = true;
+        child.kill();
+        jsonReply(res, 504, { error: 'workiq timed out after 60s' });
+      }
+      resolve();
+    }, 60_000);
+  });
+}
+
 const server = http.createServer((req, res) => {
   const method = req.method || 'GET';
   const pathname = new URL(req.url || '/', 'http://localhost').pathname;
@@ -139,6 +215,12 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  // Route: POST /api/workiq/ask — proxy to WorkIQ (M365 Copilot) from server TTY
+  if (method === 'POST' && pathname === '/api/workiq/ask') {
+    void handleWorkiqAsk(req, res);
+    return;
+  }
+
   // Route: demo-setup is handled here in demo-server (host concern)
   const boardSegMatch = pathname.match(BOARD_SEG_RE);
   if (boardSegMatch && boardSegMatch[2] === 'demo-setup') {
@@ -166,4 +248,5 @@ server.listen(PORT, '127.0.0.1', () => {
   console.log(`  POST ${runtime.apiBasePath}/:boardId/cards/:id/files`);
   console.log(`  GET  ${runtime.apiBasePath}/:boardId/cards/:id/files/:idx`);
   console.log(`  GET  ${runtime.apiBasePath}/:boardId/cards/:id/chats`);
+  console.log(`  POST /api/workiq/ask  {query}              <- WorkIQ (M365 Copilot) proxy`);
 });

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="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.6/browser/card-compute.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.6/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.6/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/board-livegraph-engine.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">
@@ -31,7 +31,7 @@
     </div>
 
     <div class="alert alert-info small py-2 mb-3">
-      Browser runtime mode: sources are executed in-browser through an opaque task executor.
+      Browser runtime mode: source_defs are executed in-browser through an opaque task executor.
       Card source definitions are treated as task-executor-owned metadata.
     </div>
 
@@ -341,7 +341,7 @@
         return cards.every((card) => {
           const artifact = cardRuntimeById[card.id];
           if (!artifact || typeof artifact !== 'object') return false;
-          if (card.sources && card.sources.length > 0) {
+          if (card.source_defs && card.source_defs.length > 0) {
             if (!(artifact.fetched_sources && typeof artifact.fetched_sources === 'object' && !Array.isArray(artifact.fetched_sources))) return false;
           }
           if (card.requires && card.requires.length > 0) {
@@ -517,7 +517,7 @@
         runtime = createBoardLiveGraphRuntime(loaded.cards, {
           taskExecutor: async function ({ card }) {
             const out = {};
-            for (const sourceDef of (card.sources || [])) {
+            for (const sourceDef of (card.source_defs || [])) {
               const payload = await mockServer.fetchSource(card, sourceDef);
               if (payload !== null && payload !== undefined) out[sourceDef.bindTo] = payload;
             }

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

@@ -16,10 +16,10 @@
   </style>
   <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.6/browser/card-compute.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.6/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.6/browser/board-livegraph-engine.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.6/browser/board-livecards-runtime-client.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/board-livecards-runtime-client.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">