yaml-flow 4.0.0 → 5.0.0

package/examples/example-board/reusable-board-runtime-client.js

@@ -0,0 +1,265 @@
+(function () {
+  function clone(x) {
+    return JSON.parse(JSON.stringify(x));
+  }
+
+  function replaceNodeInPlace(target, source) {
+    Object.keys(target).forEach((k) => delete target[k]);
+    Object.assign(target, clone(source));
+  }
+
+  function stableNodeString(node) {
+    return JSON.stringify(node);
+  }
+
+  function createBoardRuntimeClient(options) {
+    if (!options || typeof options !== 'object') {
+      throw new Error('options are required');
+    }
+
+    const fetchServer = options.fetchServer;
+    const boardPaths = options.boardPaths;
+    const buildLiveCardModelsFromArtifacts = options.buildLiveCardModelsFromArtifacts;
+    const getServerOrigin = options.getServerOrigin;
+
+    if (typeof fetchServer !== 'function') throw new Error('options.fetchServer is required');
+    if (typeof boardPaths !== 'function') throw new Error('options.boardPaths is required');
+    if (typeof buildLiveCardModelsFromArtifacts !== 'function') {
+      throw new Error('options.buildLiveCardModelsFromArtifacts is required');
+    }
+    if (typeof getServerOrigin !== 'function') throw new Error('options.getServerOrigin is required');
+
+    let nodesById = {};
+    let board = null;
+    let sse = null;
+    let currentMode = String(options.initialMode || 'board');
+    const canvas = options.canvas && typeof options.canvas === 'object'
+      ? options.canvas
+      : { height: '72vh', overflow: 'auto' };
+
+    function syncBoardNodes(nextNodes) {
+      const existingIds = new Set(board ? board.nodes.map((n) => n.id) : []);
+      const nextById = Object.fromEntries(nextNodes.map((n) => [n.id, n]));
+      let changed = false;
+
+      if (board) {
+        for (const id of existingIds) {
+          if (!nextById[id]) {
+            board.remove(id);
+            changed = true;
+          }
+        }
+      }
+
+      for (const nextNode of nextNodes) {
+        const existing = nodesById[nextNode.id];
+        if (existing) {
+          const prevStr = stableNodeString(existing);
+          const nextStr = stableNodeString(nextNode);
+          if (prevStr !== nextStr) {
+            replaceNodeInPlace(existing, nextNode);
+            changed = true;
+          }
+        } else {
+          nodesById[nextNode.id] = clone(nextNode);
+          if (board) board.add(nodesById[nextNode.id]);
+          changed = true;
+        }
+      }
+
+      if (board && changed) board.refresh();
+    }
+
+    async function uploadCardFile(boardId, cardId, file, opts) {
+      if (!file) return null;
+      const optionsObj = opts && typeof opts === 'object' ? opts : {};
+      const inChat = optionsObj.inChat === true;
+      const fileName = typeof file.name === 'string' ? file.name : 'upload.bin';
+      const contentType = file.type || 'application/octet-stream';
+      const paths = boardPaths(boardId);
+      const uploadPath = inChat
+        ? `${paths.cardFile(cardId)}?inChat=true`
+        : paths.cardFile(cardId);
+
+      const upload = await fetchServer(uploadPath, {
+        method: 'POST',
+        headers: {
+          'content-type': contentType,
+          'x-file-name': encodeURIComponent(fileName),
+        },
+        body: file,
+      });
+
+      if (!upload.ok) {
+        const errText = await upload.text();
+        throw new Error(`Upload failed (${upload.status}): ${errText || 'unknown error'}`);
+      }
+
+      const payload = await upload.json();
+      return payload && payload.file ? payload.file : null;
+    }
+
+    async function uploadActionFiles(boardId, cardId, actionType, payload) {
+      if (actionType !== 'chat-send' && actionType !== 'file-upload') return payload || {};
+      const nextPayload = { ...(payload || {}) };
+      const rawFiles = Array.isArray(nextPayload.files) ? nextPayload.files : [];
+      if (!rawFiles.length) {
+        nextPayload.files = [];
+        return nextPayload;
+      }
+
+      const uploaded = [];
+      for (const file of rawFiles) {
+        const fileMeta = await uploadCardFile(boardId, cardId, file, { inChat: actionType === 'chat-send' });
+        if (fileMeta) uploaded.push(fileMeta);
+      }
+
+      // For chat uploads, server-side file API already records file metadata and emits system chat logs.
+      nextPayload.files = actionType === 'chat-send' ? [] : uploaded;
+      return nextPayload;
+    }
+
+    async function bootstrapBoard(params) {
+      const p = params && typeof params === 'object' ? params : {};
+      const boardId = String(p.boardId || 'default');
+      const taskExecutorPath = typeof p.taskExecutorPath === 'string' ? p.taskExecutorPath.trim() : '';
+      const runDemoSetup = p.runDemoSetup !== false;
+      const mode = String(p.mode || currentMode || 'board');
+      const rootEl = p.rootElement;
+      if (!rootEl) throw new Error('bootstrapBoard requires params.rootElement');
+
+      const paths = boardPaths(boardId);
+
+      if (runDemoSetup) {
+        const setup = await fetchServer(paths.demoSetup);
+        if (!setup.ok) throw new Error(`Server demo-setup failed (${setup.status}).`);
+      }
+
+      const initBoardPath = taskExecutorPath
+        ? `${paths.initBoard}?taskExecutorPath=${encodeURIComponent(taskExecutorPath)}`
+        : paths.initBoard;
+      const initBoardRes = await fetchServer(initBoardPath);
+      if (!initBoardRes.ok) throw new Error(`Server init-board failed (${initBoardRes.status}).`);
+
+      const bootstrapCardsRes = await fetchServer(paths.bootstrapCards);
+      if (!bootstrapCardsRes.ok) {
+        throw new Error(`Server bootstrap-cards failed (${bootstrapCardsRes.status}).`);
+      }
+
+      const payload = await bootstrapCardsRes.json();
+      const cards = buildLiveCardModelsFromArtifacts(payload);
+      if (!Array.isArray(cards)) throw new Error('Server payload missing published runtime artifacts');
+
+      nodesById = {};
+      for (const n of cards) nodesById[n.id] = clone(n);
+
+      const engine = LiveCard.init({
+        resolve: (id) => nodesById[id],
+        onPatchState: async (id, patch) => {
+          await fetchServer(paths.patchCard(id), {
+            method: 'PATCH',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(patch || {}),
+          });
+        },
+        onRefresh: async (id) => {
+          await fetchServer(paths.patchCard(id), {
+            method: 'PATCH',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({}),
+          });
+        },
+        onAction: async (id, actionType, actionPayload) => {
+          const uploadedPayload = await uploadActionFiles(boardId, id, actionType, actionPayload);
+          await fetchServer(paths.cardAction(id), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ actionType, payload: uploadedPayload || {} }),
+          });
+        },
+        getChatMessages: async (id) => {
+          const res = await fetchServer(paths.cardChats(id));
+          if (!res.ok) return [];
+          const chatPayload = await res.json();
+          const items = Array.isArray(chatPayload && chatPayload.messages) ? chatPayload.messages : [];
+          return items.map((m) => ({
+            role: m && typeof m.role === 'string' ? m.role : 'system',
+            text: m && typeof m.text === 'string' ? m.text : '',
+            files: [],
+          }));
+        },
+      });
+
+      rootEl.innerHTML = '';
+      board = LiveCard.Board(engine, rootEl, {
+        nodes: Object.values(nodesById),
+        mode,
+        canvas,
+      });
+      currentMode = mode;
+
+      const origin = getServerOrigin();
+      if (!origin) {
+        throw new Error('Server origin not resolved before SSE start');
+      }
+      sse = new EventSource(`${origin}${paths.stream}`);
+      sse.onmessage = function (evt) {
+        try {
+          const update = JSON.parse(evt.data || '{}');
+          syncBoardNodes(buildLiveCardModelsFromArtifacts(update));
+          if (board && board.engine && typeof board.engine.onServerSseEvent === 'function') {
+            board.engine.onServerSseEvent();
+          } else if (board && board.engine && typeof board.engine.refreshOpenChatModal === 'function') {
+            board.engine.refreshOpenChatModal();
+          }
+        } catch (err) {
+          console.warn('Bad SSE payload', err);
+        }
+      };
+
+      return board;
+    }
+
+    function dispose() {
+      if (sse) {
+        sse.close();
+        sse = null;
+      }
+      board = null;
+      nodesById = {};
+    }
+
+    function setMode(mode) {
+      currentMode = String(mode || 'board');
+      if (board) board.setMode(currentMode);
+    }
+
+    function autoLayout() {
+      if (!board) return;
+      board.setMode('canvas');
+      currentMode = 'canvas';
+      board.autoLayout();
+    }
+
+    function setDevMode(enabled) {
+      if (board) board.setDevMode(Boolean(enabled));
+    }
+
+    function getCurrentMode() {
+      return currentMode;
+    }
+
+    return {
+      bootstrapBoard,
+      dispose,
+      setMode,
+      autoLayout,
+      setDevMode,
+      getCurrentMode,
+    };
+  }
+
+  window.ReusableBoardRuntimeClient = {
+    createBoardRuntimeClient,
+  };
+})();

package/examples/example-board/reusable-runtime-artifacts-adapter.js

@@ -0,0 +1,233 @@
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function taskStatusToCardStatus(taskStatus) {
+  if (taskStatus === 'running' || taskStatus === 'in-progress') return 'loading';
+  if (taskStatus === 'failed') return 'error';
+  if (taskStatus === 'completed') return 'fresh';
+  return 'fresh';
+}
+
+function cardStatusToTaskStatus(cardStatus) {
+  if (cardStatus === 'loading') return 'in-progress';
+  if (cardStatus === 'error') return 'failed';
+  if (cardStatus === 'stale') return 'pending';
+  if (cardStatus === 'fresh') return 'completed';
+  return 'pending';
+}
+
+function ensureObject(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  return value;
+}
+
+function normalizeCardRuntimeArtifact(cardId, artifact) {
+  const safeArtifact = artifact && typeof artifact === 'object' && !Array.isArray(artifact)
+    ? artifact
+    : {};
+
+  const cardData = safeArtifact.card_data && typeof safeArtifact.card_data === 'object' && !Array.isArray(safeArtifact.card_data)
+    ? clone(safeArtifact.card_data)
+    : {};
+
+  const computedValues = safeArtifact.computed_values && typeof safeArtifact.computed_values === 'object' && !Array.isArray(safeArtifact.computed_values)
+    ? clone(safeArtifact.computed_values)
+    : {};
+
+  const fetchedSources = safeArtifact.fetched_sources && typeof safeArtifact.fetched_sources === 'object' && !Array.isArray(safeArtifact.fetched_sources)
+    ? clone(safeArtifact.fetched_sources)
+    : {};
+
+  const requiresData = safeArtifact.requires && typeof safeArtifact.requires === 'object' && !Array.isArray(safeArtifact.requires)
+    ? clone(safeArtifact.requires)
+    : {};
+
+  return {
+    schema_version: safeArtifact.schema_version || 'v1',
+    card_id: typeof safeArtifact.card_id === 'string' ? safeArtifact.card_id : cardId,
+    card_data: cardData,
+    computed_values: computedValues,
+    fetched_sources: fetchedSources,
+    requires: requiresData,
+  };
+}
+
+function resolveRequiresData(cardDefinition, dataObjectsByToken) {
+  const resolved = {};
+  const tokens = Array.isArray(cardDefinition && cardDefinition.requires) ? cardDefinition.requires : [];
+  const safeObjects = dataObjectsByToken && typeof dataObjectsByToken === 'object' && !Array.isArray(dataObjectsByToken)
+    ? dataObjectsByToken
+    : {};
+
+  for (const token of tokens) {
+    if (!Object.prototype.hasOwnProperty.call(safeObjects, token)) continue;
+    resolved[token] = clone(safeObjects[token]);
+  }
+
+  return resolved;
+}
+
+function buildLiveCardModelsFromArtifacts(payload) {
+  const safePayload = ensureObject(payload, 'payload');
+  const cardDefinitions = Array.isArray(safePayload.cardDefinitions) ? safePayload.cardDefinitions : [];
+  const statusSnapshot = safePayload.statusSnapshot && typeof safePayload.statusSnapshot === 'object' ? safePayload.statusSnapshot : {};
+  const cardRuntimeById = safePayload.cardRuntimeById && typeof safePayload.cardRuntimeById === 'object' ? safePayload.cardRuntimeById : {};
+  const dataObjectsByToken = safePayload.dataObjectsByToken && typeof safePayload.dataObjectsByToken === 'object' ? safePayload.dataObjectsByToken : {};
+  const statusCards = Array.isArray(statusSnapshot.cards) ? statusSnapshot.cards : [];
+  const statusById = new Map(statusCards.map((card) => [card.name, card]));
+
+  return cardDefinitions.map((cardDefinition) => {
+    const card = clone(cardDefinition);
+    const cardId = card && card.id;
+    if (!cardId) throw new Error('cardDefinitions entry missing id');
+
+    const statusCard = statusById.get(cardId);
+    const runtimeArtifact = normalizeCardRuntimeArtifact(cardId, cardRuntimeById[cardId]);
+
+    const cardData = {
+      ...((card.card_data && typeof card.card_data === 'object' && !Array.isArray(card.card_data)) ? card.card_data : {}),
+      ...(runtimeArtifact.card_data || {}),
+      status: taskStatusToCardStatus(statusCard && statusCard.status),
+      lastRun: (statusCard && statusCard.runtime && statusCard.runtime.last_transition_at) || null,
+    };
+
+    if (statusCard && statusCard.error && statusCard.error.message) {
+      cardData.error = statusCard.error.message;
+    }
+
+    const runtimeState = statusCard
+      ? {
+          task_status: statusCard.status || null,
+          card_status: taskStatusToCardStatus(statusCard.status),
+          runtime: clone(statusCard.runtime || {}),
+          error: statusCard.error ? clone(statusCard.error) : null,
+          blocked_by: Array.isArray(statusCard.blocked_by) ? clone(statusCard.blocked_by) : [],
+          requires_missing: Array.isArray(statusCard.requires_missing) ? clone(statusCard.requires_missing) : [],
+        }
+      : {
+          task_status: null,
+          card_status: cardData.status || 'fresh',
+          runtime: { last_transition_at: cardData.lastRun || null },
+          error: cardData.error ? { message: cardData.error } : null,
+          blocked_by: [],
+          requires_missing: [],
+        };
+
+    return {
+      id: cardId,
+      card,
+      card_data: cardData,
+      fetched_sources: runtimeArtifact.fetched_sources || {},
+      requires: resolveRequiresData(card, dataObjectsByToken),
+      computed_values: runtimeArtifact.computed_values || {},
+      runtime_state: runtimeState,
+      data_objects: clone(dataObjectsByToken),
+    };
+  });
+}
+
+function buildBrowserArtifactsFromRuntime({ boardPath, cardDefinitions, runtimeModels, graphState }) {
+  const safeCardDefinitions = Array.isArray(cardDefinitions) ? cardDefinitions : [];
+  const safeRuntimeModels = Array.isArray(runtimeModels) ? runtimeModels : [];
+  const runtimeModelById = new Map(safeRuntimeModels.map((model) => [model.id, model]));
+  const taskStates = graphState && graphState.state && graphState.state.tasks ? graphState.state.tasks : {};
+
+  const cardRuntimeById = {};
+  for (const model of safeRuntimeModels) {
+    if (!model || !model.id) continue;
+    cardRuntimeById[model.id] = {
+      schema_version: 'v1',
+      card_id: model.id,
+      card_data: clone(model.card_data || {}),
+      computed_values: clone(model.computed_values || {}),
+      fetched_sources: clone(model.fetched_sources || {}),
+      requires: clone(model.requires || {}),
+    };
+  }
+
+  const dataObjectsByToken = {};
+  for (const taskName of Object.keys(taskStates)) {
+    const taskState = taskStates[taskName] || {};
+    const taskData = taskState.data && typeof taskState.data === 'object' ? taskState.data : {};
+    const providesData = taskData.provides_data && typeof taskData.provides_data === 'object'
+      ? taskData.provides_data
+      : {};
+
+    for (const token of Object.keys(providesData)) {
+      dataObjectsByToken[token] = clone(providesData[token]);
+    }
+  }
+
+  const statusCards = safeCardDefinitions.map((cardDefinition) => {
+    const runtimeModel = runtimeModelById.get(cardDefinition.id) || {};
+    const taskState = taskStates[cardDefinition.id] || {};
+    const taskStatus = typeof taskState.status === 'string'
+      ? taskState.status
+      : cardStatusToTaskStatus(runtimeModel.card_data && runtimeModel.card_data.status);
+
+    const errorMessage = typeof taskState.error === 'string'
+      ? taskState.error
+      : runtimeModel.card_data && typeof runtimeModel.card_data.error === 'string'
+        ? runtimeModel.card_data.error
+        : null;
+
+    return {
+      name: cardDefinition.id,
+      status: taskStatus,
+      error: errorMessage ? {
+        message: errorMessage,
+        code: 'TASK_FAILED',
+        at: taskState.failedAt || null,
+        source: 'browser-runtime',
+      } : undefined,
+      requires: Array.isArray(cardDefinition.requires) ? cardDefinition.requires : [],
+      requires_satisfied: [],
+      requires_missing: [],
+      provides_declared: Array.isArray(cardDefinition.provides)
+        ? cardDefinition.provides.map((entry) => entry.bindTo)
+        : [cardDefinition.id],
+      provides_runtime: Object.keys((taskState.data && taskState.data.provides_data) || {}).sort(),
+      blocked_by: [],
+      unblocks: [],
+      runtime: {
+        attempt_count: taskState.executionCount || 0,
+        restart_count: taskState.retryCount || 0,
+        in_progress_since: taskStatus === 'in-progress' ? (taskState.startedAt || null) : null,
+        last_transition_at: taskState.lastUpdated || (runtimeModel.card_data && runtimeModel.card_data.lastRun) || null,
+        last_completed_at: taskState.completedAt || null,
+        last_restarted_at: taskState.startedAt || null,
+        status_age_ms: null,
+      },
+    };
+  });
+
+  return {
+    cardDefinitions: clone(safeCardDefinitions),
+    cardRuntimeById,
+    dataObjectsByToken,
+    statusSnapshot: {
+      schema_version: 'v1',
+      meta: { board: { path: boardPath || 'browser-runtime' } },
+      summary: {
+        card_count: statusCards.length,
+        completed: statusCards.filter((card) => card.status === 'completed').length,
+        eligible: 0,
+        pending: statusCards.filter((card) => card.status === 'pending').length,
+        blocked: 0,
+        unresolved: 0,
+        failed: statusCards.filter((card) => card.status === 'failed').length,
+        in_progress: statusCards.filter((card) => card.status === 'in-progress').length,
+        orphan_cards: 0,
+        topology: {
+          edge_count: 0,
+          max_fan_out_card: null,
+          max_fan_out: 0,
+        },
+      },
+      cards: statusCards,
+    },
+  };
+}