yaml-flow 5.2.8 → 5.4.0

package/examples/browser/boards/portfolio-tracker/portfolio-tracker.js

@@ -79,14 +79,14 @@ function cliCommand() {
 
 function runCli(args, capture = false) {
   const { cmd, prefixArgs } = cliCommand();
+  const env = { ...process.env };
+  // This demo needs real worker dispatch; suppressing spawn keeps source/inference tasks in running state.
+  delete env.BOARD_LIVE_CARDS_NO_SPAWN;
   const result = spawnSync(cmd, [...prefixArgs, ...args], {
     stdio: capture ? 'pipe' : 'inherit',
     shell: false,
     windowsHide: true,
-    env: {
-      ...process.env,
-      BOARD_LIVE_CARDS_NO_SPAWN: '1',
-    },
+    env,
     encoding: capture ? 'utf-8' : undefined,
   });
 

package/examples/example-board/agent-instructions-cardlayout.md

@@ -26,3 +26,31 @@
 - `board.col` — Bootstrap 12-column span: `3`=quarter, `4`=third, `6`=half, `8`=two-thirds, `12`=full
 - `board.order` — ascending integer, controls vertical sort in board view
 - `canvas` — pixel coordinates/size for drag-layout (canvas mode). `h` must be tall enough for all rendered content — a card with metrics + a 4-row table typically needs 400–500px. Too small a height causes an in-card scrollbar; when in doubt, size generously.
+
+---
+
+## LLM View-Type Guidance (for `kind: "ref"`)
+
+When a source uses Copilot/LLM and the card renders via a `ref` element, the model should emit a `_view` hint alongside the data.
+
+- Keep `_view.kind` within the renderer whitelist only:
+  `table`, `editable-table`, `chart`, `metric`, `list`, `badge`, `text`, `narrative`, `markdown`, `form`, `filter`, `todo`, `alert`
+- Default to `table` when uncertain.
+- Use `editable-table` for user-adjustable tabular rows and include `data.writeTo` to a `card_data` path.
+- Use `chart` only when one clear category/value mapping exists; include `data.chartType` and `data.columns: [labelField, valueField]`.
+- Keep `_view.data` minimal. Static card JSON may override it for safety.
+
+Recommended response shape:
+
+```json
+{
+  "<data_key>": [ ... ],
+  "_view": {
+    "kind": "editable-table",
+    "data": {
+      "writeTo": "card_data.<key>",
+      "columns": ["field1", "field2"]
+    }
+  }
+}
+```

package/examples/example-board/agent-instructions.md

@@ -509,11 +509,10 @@ The optional `projections` map lets a source definition declare which upstream d
     "outputFile": "quotes.json",
     "projections": {
       "holdings": "requires.holdings",
-      "topHoldings": "requires.holdings[weight > 0.05]",
-      "threshold": "card_data.threshold"
+      "url_list": "requires.holdings.ticker.('https://query1.finance.yahoo.com/v8/finance/chart/' & $ & '?interval=1d&range=1d')"
     },
-    "chartApi": {
-      "tickersFrom": "holdings.ticker"
+    "url-list": {
+      "cacheTimeout": 3600
     }
   }
 ]
@@ -538,7 +537,7 @@ node board-live-cards-cli.js describe-task-executor-capabilities --rg <boardDir>
 ```
 
 This invokes the executor's `describe-capabilities` subcommand and prints its capabilities JSON to stdout. The output includes:
-- **`sourceKinds`** — every source kind the executor handles (e.g. `mock`, `copilot`, `http`, `chartApi`), each with:
+- **`sourceKinds`** — every source kind the executor handles (e.g. `mock`, `copilot`, `workiq`, `url`, `url-list`), each with:
   - `description` — what the kind does
   - `inputSchema` — the exact `customFields` the executor expects on the source entry
   - `outputShape` — the shape of the JSON written to `--out`

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

@@ -19,7 +19,7 @@
         "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\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\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}"
+        "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}"
       }
     }
   ],
@@ -29,10 +29,12 @@
   "view": {
     "elements": [
       {
-        "kind": "editable-table",
+        "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": {
@@ -45,13 +47,21 @@
             }
           }
         }
+      },
+      {
+        "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, "notes": true }
+    "features": { "refresh": true }
   },
   "card_data": {}
 }

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

@@ -126,13 +126,67 @@ function jsonReply(res, status, payload) {
   res.end(body);
 }
 
+// ---------------------------------------------------------------------------
+// Card preparation — host-level concern, not a reusable runtime concern.
+// Copies source card JSON files into the runtime's tmpCardsDir and writes
+// the concatenated copilot-instructions.md at the board setup root.
+// The runtime's bootstrap operations assume cards are already in tmpCardsDir;
+// the host (this file) decides how and when they get there.
+// ---------------------------------------------------------------------------
+
+const _demoPrepSetupDone = new Map(); // boardId → true
+
+function isDemoSetupDone(boardId, service) {
+  return _demoPrepSetupDone.get(boardId) === true && fs.existsSync(service.tmpCardsDir);
+}
+
+function demoPrepSetup(boardId, service) {
+  const { tmpSurfaceDir, tmpCardsDir, cardsDir, gandalfCardsDir, tmpGandalfCardsDir, boardDir } = service;
+
+  fs.mkdirSync(tmpSurfaceDir, { recursive: true });
+  fs.rmSync(tmpCardsDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpCardsDir, { recursive: true });
+
+  const entries = fs.readdirSync(cardsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.toLowerCase().endsWith('.json')) continue;
+    fs.copyFileSync(path.join(cardsDir, entry.name), path.join(tmpCardsDir, entry.name));
+  }
+
+  // Copy gandalf-card templates if gandalfCardsDir is configured.
+  if (gandalfCardsDir && fs.existsSync(gandalfCardsDir)) {
+    fs.rmSync(tmpGandalfCardsDir, { recursive: true, force: true });
+    fs.mkdirSync(tmpGandalfCardsDir, { recursive: true });
+    for (const entry of fs.readdirSync(gandalfCardsDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.json')) continue;
+      fs.copyFileSync(path.join(gandalfCardsDir, entry.name), path.join(tmpGandalfCardsDir, entry.name));
+    }
+  }
+
+  // Concatenate agent-instructions*.md into copilot-instructions.md at boardSetupRoot.
+  const boardSetupRoot = path.dirname(boardDir);
+  const srcDir = path.dirname(cardsDir);
+  const agentInstructionFiles = ['agent-instructions.md', 'agent-instructions-cardlayout.md'];
+  const parts = [];
+  for (const fname of agentInstructionFiles) {
+    const fpath = path.join(srcDir, fname);
+    if (fs.existsSync(fpath)) parts.push(fs.readFileSync(fpath, 'utf-8').trimEnd());
+  }
+  if (parts.length > 0) {
+    fs.writeFileSync(path.join(boardSetupRoot, 'copilot-instructions.md'), parts.join('\n\n') + '\n', 'utf-8');
+  }
+
+  _demoPrepSetupDone.set(boardId, true);
+}
+
 async function handleDemoSetup(req, res, boardId) {
   try {
-    const { service, boardRoot } = runtime.requireBoardService(boardId);
+    const { service } = runtime.requireBoardService(boardId);
     let setupPerformed = false;
 
-    if (!service.isDemoSetupDone()) {
-      service.ensureDemoSetup();
+    if (!isDemoSetupDone(boardId, service)) {
+      demoPrepSetup(boardId, service);
       setupPerformed = true;
     }
 
@@ -168,26 +222,38 @@ async function handleWorkiqAsk(req, res) {
   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) => {
-      jsonReply(res, 500, { error: `workiq spawn error: ${err.message}` });
+      if (!responded) {
+        responded = true;
+        clearTimeout(timeoutId);
+        jsonReply(res, 500, { error: `workiq spawn error: ${err.message}` });
+      }
       resolve();
     });
     child.on('close', (code) => {
-      if (code !== 0) {
-        jsonReply(res, 500, { error: `workiq exited ${code}`, stderr });
-      } else {
-        jsonReply(res, 200, { response: stdout });
+      if (!responded) {
+        responded = true;
+        clearTimeout(timeoutId);
+        if (code !== 0) {
+          jsonReply(res, 500, { error: `workiq exited ${code}`, stderr });
+        } else {
+          jsonReply(res, 200, { response: stdout });
+        }
       }
       resolve();
     });
-    setTimeout(() => {
-      child.kill();
-      jsonReply(res, 504, { error: 'workiq timed out after 60s' });
+    const timeoutId = setTimeout(() => {
+      if (!responded) {
+        responded = true;
+        child.kill();
+        jsonReply(res, 504, { error: 'workiq timed out after 60s' });
+      }
       resolve();
     }, 60_000);
   });

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.8/browser/card-compute.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.0/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.0/browser/board-livegraph-engine.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">
@@ -378,7 +378,7 @@
 
         return {
           fetchSource: async function (card, sourceDef) {
-            // chartApi source with mock="quotes" → return mock quote data
+            // mock source with mock="quotes" → return mock quote data
             if (sourceDef && sourceDef.mock === 'quotes') return clone(quoteData);
             // copilot source → return mock analysis object
             if (sourceDef && sourceDef.copilot) return clone(mockAnalysis);

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.8/browser/card-compute.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/board-livegraph-engine.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/board-livecards-runtime-client.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.0/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.0/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.0/browser/board-livecards-runtime-client.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">

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

@@ -45,8 +45,7 @@
  *   - { "url-list": { method?, headers?, cacheTimeout? } }
  *       → fan-out over _projections.url_list (string[]); returns array of responses.
  *         Build url_list in projections: e.g. `requires.holdings.ticker.('https://host/' & $ & '?q=1')`
- *   - { chartApi: { url, headers? }, tickersFrom }  → removed; use url-list instead
- *     prefer url-list for new sources
+ *     Prefer url-list for multi-URL fan-out sources.
  *   A real executor can also handle: graphapi, teams, mail, incidentdb, script, etc.
  *
  * url / url-list notes:
@@ -137,6 +136,26 @@ function interpolatePrompt(template, args) {
   });
 }
 
+// Reusable prompt fragments available to all copilot source templates.
+// Source definitions can interpolate them with {{view_kind_guidance}} and {{card_layout_guidance}}.
+const COPILOT_PROMPT_CONTEXT = {
+  view_kind_guidance: [
+    'VIEW KIND GUIDANCE (for dynamic ref rendering):',
+    '- Return a _view object whenever your output data is meant for a ref element.',
+    '- Allowed _view.kind values only: table, editable-table, chart, metric, list, badge, text, narrative, markdown, form, filter, todo, alert.',
+    '- If uncertain, use "table".',
+    '- For array rows that users should edit, prefer "editable-table" and set _view.data.writeTo to a card_data path.',
+    '- For chart, set _view.data.chartType and _view.data.columns with [labelField, valueField].',
+    '- Keep _view.data minimal and valid JSON (no comments, no trailing text).',
+  ].join('\n'),
+  card_layout_guidance: [
+    'CARD LAYOUT GUIDANCE:',
+    '- Prefer compact outputs that fit a card: one primary structure plus concise rationale text.',
+    '- Avoid repeating values already present in upstream inputs.',
+    '- If you produce both machine-readable and human-readable content, keep machine-readable fields top-level and concise prose in a separate field.',
+  ].join('\n'),
+};
+
 /**
  * Fetch a URL using the system curl binary (synchronous, no Node event-loop handles).
  * Throws if curl exits non-zero (e.g. HTTP 4xx/5xx with -f, or network error).
@@ -167,6 +186,7 @@ function resolveCopilotPrompt(sourceDef) {
   // evaluated by the engine from card_data/requires before invoking this executor.
   // Explicit args defined on the source take highest precedence.
   const interpolationContext = {
+    ...COPILOT_PROMPT_CONTEXT,
     ...sourceDef._projections,
     ...args,
   };

package/package.json

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

package/schema/live-cards.schema.json

@@ -126,7 +126,7 @@
         "kind":      {
           "enum": ["metric", "table", "editable-table", "chart", "form", "filter", "list",
                    "notes", "todo", "alert", "narrative", "badge", "text",
-                   "markdown", "custom", "actions"]
+                   "markdown", "ref", "custom", "actions"]
         },
         "label":     { "type": "string", "description": "Heading above this element" },
         "className": { "type": "string", "description": "Bootstrap grid class, e.g. 'col-12 col-md-6'" },