yaml-flow 4.0.0 → 5.0.0

package/examples/example-board/cards/card-ex-narrative.json

@@ -0,0 +1,36 @@
+{
+  "id": "card-ex-narrative",
+  "meta": {
+    "title": "Sales Insight",
+    "tags": [],
+    "desc": "AI-generated narrative from Copilot source execution"
+  },
+  "requires": ["orders", "prices"],
+  "compute": [
+    {
+      "bindTo": "orderCount",
+      "expr": "$count(requires.orders)"
+    },
+    {
+      "bindTo": "totalRevenue",
+      "expr": "$sum(requires.orders.amount)"
+    }
+  ],
+  "sources": [
+    {
+      "bindTo": "raw",
+      "outputFile": "card-ex-narrative-raw.json",
+      "copilot": {
+        "prompt_template": "You are a concise sales analyst. Write 5-7 bullet points about business signals to monitor this week for a small B2B widget company. Keep it under 120 words."
+      }
+    }
+  ],
+  "view": {
+    "elements": [
+      { "kind": "narrative", "data": { "bind": "fetched_sources.raw" } }
+    ],
+    "layout": { "board": { "col": 6, "order": 10 }, "canvas": { "x": 600, "y": 800, "w": 350, "h": 250 } },
+    "features": { "refresh": true, "chat": true }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-ex-source-http.json

@@ -0,0 +1,28 @@
+{
+  "id": "card-ex-source-http",
+  "meta": {
+    "title": "Product Prices",
+    "tags": ["data", "linked"],
+    "desc": "Fetches pricing for products derived from upstream order data"
+  },
+  "requires": ["orders"],
+  "provides": [{ "bindTo": "prices", "src": "fetched_sources.raw" }],
+  "sources": [{
+    "bindTo": "raw",
+    "outputFile": "card-ex-source-http-raw.json",
+    "mock": "prices"
+  }],
+  "compute": [
+    {
+      "bindTo": "PRODUCT_LIST",
+      "expr": "$join($distinct(requires.orders.product), ',')"
+    }
+  ],
+  "view": {
+    "elements": [
+      { "kind": "table", "data": { "bind": "fetched_sources.raw", "columns": ["product", "price", "currency"], "sortable": true } }
+    ],
+    "layout": { "board": { "col": 6, "order": 2 }, "canvas": { "x": 450, "y": 50, "w": 350, "h": 220 } }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-ex-source.json

@@ -0,0 +1,21 @@
+{
+  "id": "card-ex-source",
+  "meta": {
+    "title": "Order Data",
+    "tags": ["data"],
+    "desc": "Root data source — fetches order records via a script"
+  },
+  "provides": [{ "bindTo": "orders", "src": "fetched_sources.raw" }],
+  "sources": [{
+    "bindTo": "raw",
+    "outputFile": "card-ex-source-raw.json",
+    "mock": "orders"
+  }],
+  "view": {
+    "elements": [
+      { "kind": "table", "data": { "bind": "fetched_sources.raw", "columns": ["id", "product", "quantity", "amount", "region"], "maxRows": 10 } }
+    ],
+    "layout": { "board": { "col": 6, "order": 1 }, "canvas": { "x": 50, "y": 50, "w": 350, "h": 220 } }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-ex-status.json

@@ -0,0 +1,35 @@
+{
+  "id": "card-ex-status",
+  "meta": {
+    "title": "Revenue Health",
+    "tags": [],
+    "desc": "Status badge with threshold logic — JSONata ternary for green/amber/red"
+  },
+  "requires": ["orders"],
+  "compute": [
+    { "bindTo": "totalRevenue", "expr": "$sum(requires.orders.amount)" },
+    { "bindTo": "orderCount",   "expr": "$count(requires.orders)" },
+    {
+      "bindTo": "health",
+      "expr": "computed_values.totalRevenue > 100000 ? { 'label': 'Healthy', 'value': computed_values.totalRevenue, 'orders': computed_values.orderCount } : computed_values.totalRevenue > 50000 ? { 'label': 'Moderate', 'value': computed_values.totalRevenue, 'orders': computed_values.orderCount } : { 'label': 'Low', 'value': computed_values.totalRevenue, 'orders': computed_values.orderCount }"
+    }
+  ],
+  "view": {
+    "elements": [
+      {
+        "kind": "badge",
+        "data": {
+          "bind": "computed_values.health.label",
+          "colorMap": { "Healthy": "success", "Moderate": "warning", "Low": "danger" }
+        }
+      },
+      {
+        "kind": "metric",
+        "label": "Revenue",
+        "data": { "bind": "computed_values.health.value" }
+      }
+    ],
+    "layout": { "board": { "col": 3, "order": 8 }, "canvas": { "x": 450, "y": 530, "w": 200, "h": 170 } }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-ex-table.json

@@ -0,0 +1,30 @@
+{
+  "id": "card-ex-table",
+  "meta": {
+    "title": "Order Details",
+    "tags": [],
+    "desc": "Filtered and sorted table — combines source data with user filter selections"
+  },
+  "requires": ["orders", "selections"],
+  "compute": [
+    {
+      "bindTo": "filtered",
+      "expr": "[$filter(requires.orders, function($v){ ($exists(requires.selections.region) ? $v.region = requires.selections.region : true) and ($exists(requires.selections.product) ? $v.product = requires.selections.product : true) })^(>amount)#$i[$i<20]]"
+    }
+  ],
+  "view": {
+    "elements": [
+      {
+        "kind": "table",
+        "data": {
+          "bind": "computed_values.filtered",
+          "columns": ["id", "product", "quantity", "amount", "region"],
+          "sortable": true,
+          "maxRows": 20
+        }
+      }
+    ],
+    "layout": { "board": { "col": 8, "order": 7 }, "canvas": { "x": 50, "y": 800, "w": 500, "h": 250 } }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-ex-todo.json

@@ -0,0 +1,29 @@
+{
+  "id": "card-ex-todo",
+  "meta": {
+    "title": "Action Items",
+    "tags": [],
+    "desc": "Interactive todo list — persistent user input via writeTo"
+  },
+  "view": {
+    "elements": [
+      {
+        "kind": "todo",
+        "label": "Tasks",
+        "data": {
+          "bind": "card_data.items",
+          "writeTo": "card_data.items",
+          "placeholder": "No tasks yet — add one above"
+        }
+      }
+    ],
+    "layout": { "board": { "col": 4, "order": 11 }, "canvas": { "x": 700, "y": 320, "w": 260, "h": 180 } }
+  },
+  "card_data": {
+    "items": [
+      { "text": "Set up task-executor for your data sources", "done": false },
+      { "text": "Configure board.yaml connections", "done": false },
+      { "text": "Run board-live-cards-cli init", "done": false }
+    ]
+  }
+}

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// demo-chat-handler.js — Echo chat handler for demo/example boards.
+//
+// Invoked by reusable-server-runtime after a user chat message is persisted,
+// when a .chat-handler file is present in the board runtime directory.
+//
+// Invocation contract:
+//   node demo-chat-handler.js --boardId <id> --cardId <id> --extra <json>
+//
+// --extra JSON shape: { chatDir: "<abs path>", boardDir: "<abs path>", lastChatFile: "<filename>" }
+//
+// This demo handler:
+//   1. Reads the content of the last chat file (the user message just written).
+//   2. Computes the next serial by incrementing the leading number from lastChatFile.
+//   3. Writes <nextSerial>-assistant.txt to chatDir with: "Echoing <original content>"
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const idx = args.indexOf(name);
+  return idx !== -1 && args[idx + 1] !== undefined ? args[idx + 1] : null;
+}
+
+const boardId     = getArg('--boardId') || '';
+const cardId      = getArg('--cardId') || '';
+const extraStr    = getArg('--extraEncJson') || '';
+
+let extra = {};
+try {
+  extra = JSON.parse(Buffer.from(extraStr, 'base64').toString('utf-8'));
+} catch {
+  console.error('[demo-chat-handler] could not parse --extra JSON');
+  process.exit(0);
+}
+
+const { chatDir, lastChatFile } = extra;
+
+if (!chatDir || !lastChatFile) {
+  console.error('[demo-chat-handler] --extra must contain chatDir and lastChatFile');
+  process.exit(0);
+}
+
+// Read the user message from the last chat file.
+const lastChatPath = path.join(chatDir, lastChatFile);
+let content = '';
+try {
+  content = fs.readFileSync(lastChatPath, 'utf-8').trim();
+} catch (err) {
+  console.error(`[demo-chat-handler] could not read ${lastChatPath}: ${err.message}`);
+  process.exit(0);
+}
+
+// Derive next serial by incrementing the leading digits in lastChatFile.
+// e.g. "007_user.txt" → 7 → next = 8 → "008-assistant.txt"
+const serialMatch = String(lastChatFile).match(/^(\d+)/);
+const nextSerial = serialMatch ? parseInt(serialMatch[1], 10) + 1 : 1;
+const nextName = `${String(nextSerial).padStart(3, '0')}-assistant.txt`;
+const nextPath = path.join(chatDir, nextName);
+
+try {
+  fs.writeFileSync(nextPath, `Echoing ${content}\n`, 'utf-8');
+  console.log(`[demo-chat-handler] boardId="${boardId}" cardId="${cardId}" wrote echo → ${nextPath}`);
+} catch (err) {
+  console.error(`[demo-chat-handler] write failed: ${err.message}`);
+  process.exit(0);
+}

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  createMultiBoardServerRuntime,
+  createRuntimeRequestDispatcher,
+  isRuntimeRoute,
+} from './reusable-server-runtime.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PORT = Number(process.env.DEMO_SERVER_PORT || 7799);
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Headers': 'content-type,x-file-name',
+  'Access-Control-Allow-Methods': 'GET,POST,PATCH,OPTIONS',
+};
+
+const runtime = createMultiBoardServerRuntime({
+  apiBasePath: '/api/boards',
+  defaultTaskExecutorPath: process.env.DEMO_TASK_EXECUTOR_PATH || path.join(__dirname, 'demo-task-executor.js'),
+});
+
+const dispatch = createRuntimeRequestDispatcher(runtime);
+
+// Board-id segment regex: /api/boards/:boardId/...
+const BOARD_SEG_RE = /^\/api\/boards\/([^/]+)\/(.+)$/;
+
+function jsonReply(res, status, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { ...CORS_HEADERS, 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(body);
+}
+
+async function handleDemoSetup(req, res, boardId) {
+  const url = new URL(req.url, 'http://localhost');
+  const reset = String(url.searchParams.get('reset') || '').toLowerCase() === 'true';
+  try {
+    const result = runtime.performDemoSetup(boardId, reset);
+    jsonReply(res, 200, result);
+  } catch (err) {
+    jsonReply(res, err.statusCode || 500, { error: String((err && err.message) || err) });
+  }
+}
+
+const server = http.createServer((req, res) => {
+  const method = req.method || 'GET';
+  const pathname = new URL(req.url || '/', 'http://localhost').pathname;
+
+  if (method === 'OPTIONS') {
+    res.writeHead(204, CORS_HEADERS);
+    res.end();
+    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') {
+    void handleDemoSetup(req, res, boardSegMatch[1]);
+    return;
+  }
+
+  // All other /api/boards routes are handled by the reusable runtime
+  void dispatch(req, res);
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(`[demo-server] listening on http://127.0.0.1:${PORT}`);
+  console.log(`[demo-server] setup dir: ${runtime.setupDir}`);
+  console.log(`[demo-server] boards config: ${runtime.setupDir}/boards-config.json`);
+  console.log('[demo-server] endpoints:');
+  console.log(`  GET  ${runtime.apiBasePath}                          <- list boards`);
+  console.log(`  POST ${runtime.apiBasePath}  {id, label?}            <- register board`);
+  console.log(`  GET  ${runtime.apiBasePath}/:boardId/demo-setup`);
+  console.log(`  GET  ${runtime.apiBasePath}/:boardId/bootstrap`);
+  console.log(`  GET  ${runtime.apiBasePath}/:boardId/sse`);
+  console.log(`  GET  ${runtime.apiBasePath}/:boardId/board-status`);
+  console.log(`  PATCH ${runtime.apiBasePath}/:boardId/cards/:id`);
+  console.log(`  POST ${runtime.apiBasePath}/:boardId/cards/:id/actions`);
+  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`);
+});