yaml-flow 3.1.0 → 4.0.0

package/browser/live-cards.js

@@ -1,8 +1,14 @@
 // live-cards.js — LiveCards v3: Node-based Board/Canvas engine
 //
-// Schema: Each node has { id, type, meta, data, view?, source?, state, compute? }
-//   type "card"   — renderable node with view.elements[]
-//   type "source" — data-only node (no view, shown as pill in canvas)
+// Schema: Each node has { id, state } required; all else optional.
+//   id, meta, state, requires, provides, sources, compute, view
+//   Nodes with view render as cards; nodes with sources but no view render as source pills in canvas.
+//   compute[] — ordered array of { bindTo, expr } JSONata steps → writes to node.computed_values (ephemeral)
+//   sources[] — open objects: only bindTo + outputFile matter to the engine; all other fields are
+//               passed verbatim to the board's task-executor (--in JSON). Users define their own
+//               shape (kind, url, mailbox, channel, model, ...) per executor.
+//   requires[] — upstream node IDs; engine subscribes automatically
+//   provides[] — [{ bindTo, src }] explicit downstream token bindings
 //
 // Uses Bootstrap 5 for layout/forms, optional Chart.js for charts.
 // Uses CardCompute (card-compute.js) for declarative compute expressions.
@@ -85,9 +91,15 @@ var LiveCard = (function () {
     return String(str).replace(/[&<>"']/g, ch => _escMap[ch]);
   }
 
+  function _pathParts(path) {
+    if (!path || typeof path !== 'string') return [];
+    // Support both dot notation (a.b.c) and bracket notation (a.b[0].c).
+    return path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+  }
+
   function _deepGet(obj, path) {
     if (!path || !obj) return undefined;
-    const parts = path.split('.');
+    const parts = _pathParts(path);
     let cur = obj;
     for (let i = 0; i < parts.length; i++) {
       if (cur == null) return undefined;
@@ -97,7 +109,8 @@ var LiveCard = (function () {
   }
 
   function _deepSet(obj, path, value) {
-    const parts = path.split('.');
+    const parts = _pathParts(path);
+    if (!parts.length) return;
     let cur = obj;
     for (let i = 0; i < parts.length - 1; i++) {
       if (cur[parts[i]] == null || typeof cur[parts[i]] !== 'object') cur[parts[i]] = {};
@@ -187,11 +200,11 @@ var LiveCard = (function () {
     }
 
     function _runCompute(node) {
-      if (!node.compute) return;
-      if (typeof CardCompute !== 'undefined') {
-        try { CardCompute.run(node); }
-        catch (e) { console.error('LiveCard compute error', node.id, e); }
-      }
+      if (!node.compute || !node.compute.length) return Promise.resolve();
+      if (typeof CardCompute === 'undefined') return Promise.resolve();
+      return CardCompute.run(node).catch(function (e) {
+        console.error('LiveCard compute error', node.id, e);
+      });
     }
 
     function _resolveBind(node, bind) {
@@ -213,7 +226,7 @@ var LiveCard = (function () {
     }
 
     function _autoSubscribe(node) {
-      const requires = (node.data && node.data.requires) || [];
+      const requires = node.requires || [];
       if (!requires.length) return;
       const cleanup = _getCleanup(node.id);
       cleanup.unsubs = requires.map(upId => subscribe(upId, () => {
@@ -221,9 +234,10 @@ var LiveCard = (function () {
         if (!info || !info.resultEl) return;
         const updated = cfg.resolve(node.id);
         if (!updated) return;
-        _runCompute(updated);
-        _renderElements(updated, info.resultEl);
-        notify(node.id);
+        _runCompute(updated).then(function () {
+          _renderElements(updated, info.resultEl);
+          notify(node.id);
+        });
       }));
     }
 
@@ -1042,8 +1056,8 @@ var LiveCard = (function () {
       const uid = 'lc-' + (node.id || 'x');
       const features = (node.view && node.view.features) || {};
 
-      // Run compute before render
-      _runCompute(node);
+      // Run compute async before populating elements
+      // (compute is triggered in the else branch below after DOM is ready)
 
       let h = `<div class="lc-card" id="${uid}">`;
 
@@ -1094,7 +1108,7 @@ var LiveCard = (function () {
       } else if (node.state && node.state.status === 'error' && node.state.error) {
         resultEl.innerHTML = `<div class="text-danger small fw-semibold">Refresh failed</div><pre class="text-muted small mt-1" style="white-space:pre-wrap">${_esc(node.state.error)}</pre>`;
       } else {
-        _renderElements(node, resultEl);
+        _runCompute(node).then(function () { _renderElements(node, resultEl); });
       }
 
       // ---- Wire refresh ----
@@ -1181,8 +1195,7 @@ var LiveCard = (function () {
       } else if (node.state.status === 'error' && node.state.error) {
         info.resultEl.innerHTML = `<div class="text-danger small fw-semibold">Refresh failed</div><pre class="text-muted small mt-1" style="white-space:pre-wrap">${_esc(node.state.error)}</pre>`;
       } else {
-        _runCompute(node);
-        _renderElements(node, info.resultEl);
+        _runCompute(node).then(function () { _renderElements(node, info.resultEl); });
       }
     }
 
@@ -1350,7 +1363,7 @@ var LiveCard = (function () {
     }
 
     function _getRequires(node) {
-      return (node.data && node.data.requires) || [];
+      return node.requires || [];
     }
 
     function _buildCardWrapper(node) {
@@ -1361,8 +1374,9 @@ var LiveCard = (function () {
       const title = (node.meta && node.meta.title) || node.id;
       const tags = (node.meta && node.meta.tags) || [];
       let badgeHtml = '';
-      if (node.type === 'source' && node.source) {
-        badgeHtml = '<span class="badge bg-info text-dark ms-auto">' + _esc(node.source.kind || 'source') + '</span>';
+      if ((node.sources && node.sources.length) && !node.view) {
+        var src = node.sources[0] || {};
+        badgeHtml = '<span class="badge bg-info text-dark ms-auto">' + _esc(src.kind || 'source') + '</span>';
       } else if (tags.length) {
         badgeHtml = tags.map(t => '<span class="badge bg-secondary ms-1">' + _esc(t) + '</span>').join('');
       }
@@ -1379,7 +1393,7 @@ var LiveCard = (function () {
       el.className = 'lc-source-node';
       const status = (node.state && node.state.status) || 'fresh';
       const title = (node.meta && node.meta.title) || node.id;
-      const kind = (node.source && node.source.kind) || 'source';
+      const kind = (node.sources && node.sources[0] && node.sources[0].kind) || 'source';
       el.innerHTML = `<div class="lc-source-pill shadow-sm">
         ${_statusDot(status)}
         <span class="fw-medium">${_esc(title)}</span>
@@ -1396,7 +1410,7 @@ var LiveCard = (function () {
       gridEl.innerHTML = '';
 
       // Only card nodes in board mode, sorted by order
-      const cards = nodeList.filter(n => n.type === 'card').slice();
+      const cards = nodeList.filter(n => n.view).slice();
       cards.sort((a, b) => {
         const ao = (a.view && a.view.layout && a.view.layout.board && a.view.layout.board.order) || 0;
         const bo = (b.view && b.view.layout && b.view.layout.board && b.view.layout.board.order) || 0;
@@ -1477,7 +1491,7 @@ var LiveCard = (function () {
         el.style.left = x + 'px'; el.style.top = y + 'px';
         // Persist
         _positions[node.id] = Object.assign(_positions[node.id] || {}, { x, y });
-        if (node.type === 'card' && node.view) {
+        if (node.view) {
           if (!node.view.layout) node.view.layout = {};
           if (!node.view.layout.canvas) node.view.layout.canvas = {};
           node.view.layout.canvas.x = x;
@@ -1499,7 +1513,7 @@ var LiveCard = (function () {
       nodeList.forEach(node => {
         const pos = _positions[node.id] || { x: 0, y: 0 };
 
-        if (node.type === 'source') {
+        if (!node.view && (node.sources && node.sources.length)) {
           const el = _buildSourcePill(node);
           el.dataset.nodeId = node.id;
           el.style.left = pos.x + 'px';
@@ -1596,7 +1610,7 @@ var LiveCard = (function () {
           w: (_positions[n.id] && _positions[n.id].w) || cvs.defaultW,
         };
         // Sync to card nodes
-        if (n.type === 'card' && n.view) {
+        if (n.view) {
           if (!n.view.layout) n.view.layout = {};
           n.view.layout.canvas = Object.assign({}, _positions[n.id]);
         }

package/browser/live-cards.schema.json

@@ -7,9 +7,9 @@
   "definitions": {
 
     "bind_ref": {
-      "description": "A state path reference, e.g. 'state.raw_quotes' or 'state.compute_vars.total'",
+      "description": "A state path reference, e.g. 'state.raw_quotes' or 'requires.upstream'",
       "type": "string",
-      "pattern": "^state\\."
+      "pattern": "^(state|requires|computed_values)\\."
     },
 
     "bind_or_literal": {
@@ -72,39 +72,46 @@
       }
     },
 
-    "data": {
+    "requires": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "IDs of upstream nodes this node depends on"
+    },
+
+    "provides": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["bindTo", "src"],
+        "properties": {
+          "bindTo": { "type": "string", "description": "Token name published downstream" },
+          "src":    { "type": "string", "description": "Path to read value from (state.*, requires.*, computed_values.*)" }
+        }
+      },
+      "description": "Explicit bindings exposing computed/state values downstream as named tokens"
+    },
+
+    "compute_step": {
+      "description": "A single ordered compute step: reads state.*/requires.*/computed_values.*, writes to computed_values[bindTo]",
       "type": "object",
+      "required": ["bindTo", "expr"],
       "properties": {
-        "requires": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "IDs of upstream nodes this node depends on"
-        },
-        "provides": {
-          "type": "object",
-          "description": "Subset of state exposed downstream. Keys are published names, values are bind refs.",
-          "additionalProperties": { "$ref": "#/definitions/bind_or_literal" }
-        }
+        "bindTo": { "type": "string", "description": "Key in computed_values to write result" },
+        "expr":   { "type": "string", "description": "JSONata expression evaluated against { state, requires, sources, computed_values }" }
       }
     },
 
     "source_def": {
+      "description": "One source entry. The engine only cares about 'bindTo' (compute namespace key) and 'outputFile' (delivery signal). Every other property is yours — add whatever your task-executor needs: kind, url, headers, mailbox, channel, model, query, etc. The full object is passed verbatim as the --in JSON to the executor.",
       "type": "object",
-      "required": ["kind", "bindTo"],
+      "required": ["bindTo"],
+      "additionalProperties": true,
       "properties": {
-        "kind":           { "enum": ["api", "websocket", "static", "llm"] },
-        "bindTo":         { "$ref": "#/definitions/bind_ref", "description": "state path to write fetched data into" },
-        "method":         { "enum": ["GET", "POST", "PUT", "DELETE"], "default": "GET" },
-        "url_template":   { "type": "string", "description": "URL with {{var}} placeholders" },
-        "headers":        { "type": "object", "additionalProperties": { "$ref": "#/definitions/bind_or_literal" } },
-        "body_template":  { "type": "object", "description": "Request body with {{var}} placeholders or bind refs" },
-        "template_vars":  {
-          "type": "object",
-          "additionalProperties": { "$ref": "#/definitions/bind_or_literal" },
-          "description": "Variables for url/body templates — static values or bind refs"
-        },
-        "poll_interval":  { "type": "integer", "minimum": 0, "description": "Auto-refresh in seconds (0 = manual)" },
-        "transform":      { "type": "string", "description": "Dot-path to extract from response, e.g. 'data.items'" }
+        "bindTo":     { "type": "string",  "description": "Key under sources.* available in compute expressions" },
+        "outputFile": { "type": "string",  "description": "Board-relative path the executor writes its JSON result to. Presence of this file signals delivery." },
+        "optionalForCompletionGating":   { "type": "boolean", "default": false, "description": "When true this source does not gate card completion. Default false when absent, so sources are completion-gating by default." },
+        "timeout":    { "type": "integer", "minimum": 0, "default": 120000, "description": "Executor/script timeout in ms. Default: 120 000 (2 min)." },
+        "script":     { "type": "string",  "description": "Legacy direct-run: shell command executed when no .task-executor is registered. stdout is captured as the result." }
       }
     },
 
@@ -209,58 +216,33 @@
     }
   },
 
-  "oneOf": [
-    {
-      "title": "Card",
-      "description": "A renderable card node with view elements",
-      "type": "object",
-      "required": ["id", "type", "view", "state"],
-      "additionalProperties": false,
+  "title": "LiveCard",
+  "description": "A unified card node. Behavior depends on which sections are present (sources, compute, view, etc.)",
+  "type": "object",
+  "required": ["id"],
+  "additionalProperties": false,
+  "properties": {
+    "id":       { "type": "string" },
+    "requires": { "$ref": "#/definitions/requires" },
+    "provides": { "$ref": "#/definitions/provides" },
+    "meta":     { "$ref": "#/definitions/meta" },
+    "view":     { "$ref": "#/definitions/view" },
+    "state":    { "type": "object", "additionalProperties": true,
       "properties": {
-        "id":      { "type": "string" },
-        "type":    { "const": "card" },
-        "meta":    { "$ref": "#/definitions/meta" },
-        "data":    { "$ref": "#/definitions/data" },
-        "view":    { "$ref": "#/definitions/view" },
-        "state":   { "type": "object", "additionalProperties": true,
-          "properties": {
-            "status":  { "enum": ["fresh", "stale", "loading", "error"] },
-            "lastRun": { "type": "string", "format": "date-time" },
-            "error":   { "type": "string" }
-          }
-        },
-        "compute": {
-          "type": "object",
-          "description": "Derived state: key = state path to write, value = compute_expr",
-          "additionalProperties": { "$ref": "#/definitions/compute_expr" }
-        }
+        "status":  { "enum": ["fresh", "stale", "loading", "error"] },
+        "lastRun": { "type": "string", "format": "date-time" },
+        "error":   { "type": "string" }
       }
     },
-    {
-      "title": "ExternalSource",
-      "description": "A data-only node that fetches from external systems (no view)",
-      "type": "object",
-      "required": ["id", "type", "source", "state"],
-      "additionalProperties": false,
-      "properties": {
-        "id":      { "type": "string" },
-        "type":    { "const": "source" },
-        "meta":    { "$ref": "#/definitions/meta" },
-        "data":    { "$ref": "#/definitions/data" },
-        "source":  { "$ref": "#/definitions/source_def" },
-        "state":   { "type": "object", "additionalProperties": true,
-          "properties": {
-            "status":  { "enum": ["fresh", "stale", "loading", "error"] },
-            "lastRun": { "type": "string", "format": "date-time" },
-            "error":   { "type": "string" }
-          }
-        },
-        "compute": {
-          "type": "object",
-          "description": "Derived state: key = state path to write, value = compute_expr",
-          "additionalProperties": { "$ref": "#/definitions/compute_expr" }
-        }
-      }
+    "sources": {
+      "type": "array",
+      "description": "Source entries. Each entry is passed verbatim to the board's .task-executor (registered via init --task-executor) as the --in JSON file. The executor fetches/generates the data and writes JSON to --out. If no executor is registered, the built-in executor runs the entry's 'cli' command directly. Sources gate completion by default. Set optionalForCompletionGating: true for enrichment-only sources that should not block task-completed.",
+      "items": { "$ref": "#/definitions/source_def" }
+    },
+    "compute": {
+      "type": "array",
+      "description": "Ordered array of compute steps. Each reads state.*/requires.*/sources.*/computed_values.* and writes to ephemeral computed_values[bindTo].",
+      "items": { "$ref": "#/definitions/compute_step" }
     }
-  ]
+  }
 }