yaml-flow 4.0.0 → 5.0.0

package/dist/cli/board-live-cards-cli.js

@@ -1,12 +1,12 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { randomUUID, createHash } from 'crypto';
+import { randomUUID } from 'crypto';
 import { execFileSync, spawn, execFile } from 'child_process';
 import { fileURLToPath } from 'url';
 import fg from 'fast-glob';
 import { lockSync } from 'proper-lockfile';
-import jsonata from 'jsonata';
+import jsonata2 from 'jsonata';
 import 'ajv-formats';
 
 // src/cli/board-live-cards-cli.ts
@@ -638,9 +638,11 @@ var MemoryJournal = class {
     return this.buffer.length;
   }
 };
+
+// src/continuous-event-graph/reactive.ts
 function computeDataHash(data) {
   const json = stableStringify(data);
-  return createHash("sha256").update(json).digest("hex").slice(0, 16);
+  return fnv1a64Hex(json);
 }
 function stableStringify(value) {
   if (value === null || value === void 0 || typeof value !== "object") {
@@ -653,13 +655,49 @@ function stableStringify(value) {
   const keys = Object.keys(obj).sort();
   return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
 }
+function fnv1a64Hex(input) {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mod = 0xffffffffffffffffn;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = hash * prime & mod;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+function base64UrlEncode(input) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "utf8").toString("base64url");
+  }
+  if (typeof btoa === "function") {
+    const bytes = new TextEncoder().encode(input);
+    let binary = "";
+    for (const b of bytes) binary += String.fromCharCode(b);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+  }
+  throw new Error("No base64 encoder available in this runtime");
+}
+function base64UrlDecode(input) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "base64url").toString("utf8");
+  }
+  if (typeof atob === "function") {
+    const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  throw new Error("No base64 decoder available in this runtime");
+}
 function encodeCallbackToken(taskName) {
   const payload = JSON.stringify({ t: taskName, n: Date.now().toString(36) + Math.random().toString(36).slice(2, 6) });
-  return Buffer.from(payload).toString("base64url");
+  return base64UrlEncode(payload);
 }
 function decodeCallbackToken(token) {
   try {
-    const payload = JSON.parse(Buffer.from(token, "base64url").toString());
+    const payload = JSON.parse(base64UrlDecode(token));
     if (typeof payload?.t === "string") return { taskName: payload.t };
     return null;
   } catch {
@@ -936,18 +974,18 @@ function deepSet(obj, path2, value) {
 }
 async function run(node, options) {
   if (!node?.compute?.length) return node;
-  if (!node.state) node.state = {};
+  if (!node.card_data) node.card_data = {};
   node.computed_values = {};
   node._sourcesData = options?.sourcesData ?? {};
   const ctx = {
-    state: node.state,
+    card_data: node.card_data,
     requires: node.requires ?? {},
-    sources: node._sourcesData,
+    fetched_sources: node._sourcesData,
     computed_values: node.computed_values
   };
   for (const step of node.compute) {
     try {
-      const val = await jsonata(step.expr).evaluate(ctx);
+      const val = await jsonata2(step.expr).evaluate(ctx);
       deepSet(node.computed_values, step.bindTo, val);
       ctx.computed_values = node.computed_values;
     } catch (err) {
@@ -958,16 +996,16 @@ async function run(node, options) {
 }
 async function evalExpr(expr, node) {
   const ctx = {
-    state: node.state ?? {},
+    card_data: node.card_data ?? {},
     requires: node.requires ?? {},
-    sources: node._sourcesData ?? {},
+    fetched_sources: node._sourcesData ?? {},
     computed_values: node.computed_values ?? {}
   };
-  return jsonata(expr).evaluate(ctx);
+  return jsonata2(expr).evaluate(ctx);
 }
 function resolve(node, path2) {
-  if (path2.startsWith("sources.")) {
-    return deepGet(node._sourcesData ?? {}, path2.slice("sources.".length));
+  if (path2.startsWith("fetched_sources.")) {
+    return deepGet(node._sourcesData ?? {}, path2.slice("fetched_sources.".length));
   }
   return deepGet(node, path2);
 }
@@ -987,8 +1025,7 @@ var VALID_ELEMENT_KINDS = /* @__PURE__ */ new Set([
   "markdown",
   "custom"
 ]);
-var VALID_STATUSES = /* @__PURE__ */ new Set(["fresh", "stale", "loading", "error"]);
-var ALLOWED_KEYS = /* @__PURE__ */ new Set(["id", "meta", "requires", "provides", "view", "state", "compute", "sources"]);
+var ALLOWED_KEYS = /* @__PURE__ */ new Set(["id", "meta", "requires", "provides", "view", "card_data", "compute", "sources"]);
 function validateNode(node) {
   const errors = [];
   if (!node || typeof node !== "object" || Array.isArray(node)) {
@@ -999,13 +1036,8 @@ function validateNode(node) {
   for (const key of Object.keys(n)) {
     if (!ALLOWED_KEYS.has(key)) errors.push(`Unknown top-level key: "${key}"`);
   }
-  if (n.state == null || typeof n.state !== "object" || Array.isArray(n.state)) {
-    errors.push("state: required, must be an object");
-  } else {
-    const state = n.state;
-    if (state.status != null && !VALID_STATUSES.has(state.status)) {
-      errors.push(`state.status: must be one of: ${[...VALID_STATUSES].join(", ")}`);
-    }
+  if (n.card_data == null || typeof n.card_data !== "object" || Array.isArray(n.card_data)) {
+    errors.push("card_data: required, must be an object");
   }
   if (n.meta != null) {
     if (typeof n.meta !== "object" || Array.isArray(n.meta)) {
@@ -1094,17 +1126,33 @@ function validateNode(node) {
   }
   return { ok: errors.length === 0, errors };
 }
+function enrichSources(sources, context) {
+  if (!sources || sources.length === 0) return [];
+  return sources.map((src) => ({
+    ...src,
+    _requires: context.requires ?? {},
+    _sourcesData: context.sourcesData ?? {},
+    _computed_values: context.computed_values ?? {}
+  }));
+}
 var CardCompute = {
   run,
   eval: evalExpr,
   resolve,
-  validate: validateNode
+  validate: validateNode,
+  enrichSources
 };
 
 // src/cli/board-live-cards-cli.ts
 var BOARD_FILE = "board-graph.json";
 var JOURNAL_FILE = "board-journal.jsonl";
+var TASK_EXECUTOR_LOG_FILE = "task-executor.jsonl";
 var INVENTORY_FILE = "cards-inventory.jsonl";
+var RUNTIME_OUT_FILE = ".runtime-out";
+var DEFAULT_RUNTIME_OUT_DIR = "runtime-out";
+var RUNTIME_STATUS_FILE = "board-livegraph-status.json";
+var RUNTIME_CARDS_DIR = "cards";
+var RUNTIME_DATA_OBJECTS_DIR = "data-objects";
 var EMPTY_CONFIG = { settings: { completion: "manual", refreshStrategy: "data-changed" }, tasks: {} };
 var BoardJournal = class {
   journalPath;
@@ -1159,7 +1207,34 @@ function lookupCardPath(boardDir, cardId) {
 }
 function appendCardInventory(boardDir, entry) {
   const inventoryPath = path.join(boardDir, INVENTORY_FILE);
-  fs.appendFileSync(inventoryPath, JSON.stringify(entry) + "\n");
+  const normalized = { ...entry, cardFilePath: path.resolve(entry.cardFilePath) };
+  fs.appendFileSync(inventoryPath, JSON.stringify(normalized) + "\n");
+}
+function buildCardInventoryIndex(boardDir) {
+  const byCardId = /* @__PURE__ */ new Map();
+  const byCardPath = /* @__PURE__ */ new Map();
+  for (const entry of readCardInventory(boardDir)) {
+    const normalizedPath = path.resolve(entry.cardFilePath);
+    const normalizedEntry = {
+      ...entry,
+      cardFilePath: normalizedPath
+    };
+    const existingById = byCardId.get(entry.cardId);
+    if (existingById && existingById.cardFilePath !== normalizedPath) {
+      throw new Error(
+        `Inventory invariant violation: card id "${entry.cardId}" maps to multiple files: "${existingById.cardFilePath}" and "${normalizedPath}"`
+      );
+    }
+    const existingByPath = byCardPath.get(normalizedPath);
+    if (existingByPath && existingByPath.cardId !== entry.cardId) {
+      throw new Error(
+        `Inventory invariant violation: file "${normalizedPath}" maps to multiple ids: "${existingByPath.cardId}" and "${entry.cardId}"`
+      );
+    }
+    byCardId.set(entry.cardId, normalizedEntry);
+    byCardPath.set(normalizedPath, normalizedEntry);
+  }
+  return { byCardId, byCardPath };
 }
 function initBoard(dir) {
   const boardPath = path.join(dir, BOARD_FILE);
@@ -1195,7 +1270,63 @@ function saveBoard(dir, rg, journal) {
     lastDrainedJournalId: journal.lastDrainedJournalId,
     graph: snap
   };
-  fs.writeFileSync(path.join(dir, BOARD_FILE), JSON.stringify(envelope, null, 2));
+  writeJsonAtomic(path.join(dir, BOARD_FILE), envelope);
+  const live = restore(snap);
+  const statusObject = buildBoardStatusObject(dir, live);
+  writeJsonAtomic(resolveStatusSnapshotPath(dir), statusObject);
+}
+function runtimeOutConfigPath(boardDir) {
+  return path.join(boardDir, RUNTIME_OUT_FILE);
+}
+function resolveConfiguredRuntimeOutDir(boardDir) {
+  const cfgPath = runtimeOutConfigPath(boardDir);
+  if (fs.existsSync(cfgPath)) {
+    const configured = fs.readFileSync(cfgPath, "utf-8").trim();
+    if (configured) {
+      return path.isAbsolute(configured) ? configured : path.resolve(boardDir, configured);
+    }
+  }
+  const defaultDir = path.join(boardDir, DEFAULT_RUNTIME_OUT_DIR);
+  fs.writeFileSync(cfgPath, defaultDir, "utf-8");
+  return defaultDir;
+}
+function configureRuntimeOutDir(boardDir, runtimeOut) {
+  let resolved;
+  if (runtimeOut) {
+    resolved = path.isAbsolute(runtimeOut) ? runtimeOut : path.resolve(boardDir, runtimeOut);
+  } else {
+    resolved = path.join(boardDir, DEFAULT_RUNTIME_OUT_DIR);
+  }
+  fs.mkdirSync(resolved, { recursive: true });
+  fs.writeFileSync(runtimeOutConfigPath(boardDir), resolved, "utf-8");
+  return resolved;
+}
+function resolveStatusSnapshotPath(boardDir) {
+  return path.join(resolveConfiguredRuntimeOutDir(boardDir), RUNTIME_STATUS_FILE);
+}
+function resolveComputedValuesPath(boardDir, cardId) {
+  return path.join(resolveConfiguredRuntimeOutDir(boardDir), RUNTIME_CARDS_DIR, `${cardId}.computed.json`);
+}
+function resolveDataObjectsDirPath(boardDir) {
+  return path.join(resolveConfiguredRuntimeOutDir(boardDir), RUNTIME_DATA_OBJECTS_DIR);
+}
+function toDataObjectFileName(token) {
+  return token.replace(/[\\/]/g, "__");
+}
+function writeRuntimeDataObjects(boardDir, data) {
+  for (const [token, payload] of Object.entries(data)) {
+    if (!token) continue;
+    const fileName = toDataObjectFileName(token);
+    if (!fileName) continue;
+    const filePath = path.join(resolveDataObjectsDirPath(boardDir), fileName);
+    writeJsonAtomic(filePath, payload);
+  }
+}
+function writeJsonAtomic(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), "utf-8");
+  fs.renameSync(tmpPath, filePath);
 }
 function withBoardLock(boardDir, fn) {
   const boardPath = path.join(boardDir, BOARD_FILE);
@@ -1273,15 +1404,63 @@ function shouldUseShellForCommand(cmd, forceShell) {
   if (typeof forceShell === "boolean") return forceShell;
   return process.platform === "win32" && /\.(cmd|bat)$/i.test(cmd);
 }
+var _gitBashPath;
+var GIT_BASH_CACHE_FILE = path.join(os.tmpdir(), ".board-live-cards-git-bash-cache.json");
+function findGitBash() {
+  if (_gitBashPath !== void 0) return _gitBashPath;
+  if (process.platform !== "win32") return _gitBashPath = false;
+  try {
+    const cached = JSON.parse(fs.readFileSync(GIT_BASH_CACHE_FILE, "utf8"));
+    if (cached.path === false || typeof cached.path === "string" && fs.existsSync(cached.path)) {
+      return _gitBashPath = cached.path;
+    }
+  } catch {
+  }
+  const candidates = [
+    process.env.SHELL,
+    process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, "Git", "usr", "bin", "bash.exe"),
+    process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, "Git", "bin", "bash.exe"),
+    process.env["PROGRAMFILES(X86)"] && path.join(process.env["PROGRAMFILES(X86)"], "Git", "bin", "bash.exe"),
+    process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, "Programs", "Git", "bin", "bash.exe")
+  ];
+  for (const c of candidates) {
+    if (c && /bash(\.exe)?$/i.test(c) && fs.existsSync(c)) {
+      _gitBashPath = c;
+      try {
+        fs.writeFileSync(GIT_BASH_CACHE_FILE, JSON.stringify({ path: c }));
+      } catch {
+      }
+      return _gitBashPath;
+    }
+  }
+  _gitBashPath = false;
+  try {
+    fs.writeFileSync(GIT_BASH_CACHE_FILE, JSON.stringify({ path: false }));
+  } catch {
+  }
+  return _gitBashPath;
+}
+function shellQuote(s) {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
 function spawnDetachedCommand(cmd, args) {
-  const child = process.platform === "win32" ? spawn("cmd", ["/c", "start", "/b", "", cmd, ...args], {
-    stdio: "ignore",
-    windowsHide: true
-  }) : spawn(cmd, args, {
-    shell: false,
-    detached: true,
-    stdio: "ignore"
-  });
+  if (process.platform === "win32") {
+    const bash = findGitBash();
+    if (bash) {
+      const shellCmd = [cmd, ...args].map((a) => shellQuote(a.replace(/\\/g, "/"))).join(" ");
+      const child3 = spawn(bash, ["-c", shellCmd], { detached: true, stdio: "ignore", windowsHide: true });
+      child3.unref();
+      return;
+    }
+    const child2 = spawn("cmd", ["/c", "start", "/b", "", cmd, ...args], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child2.unref();
+    return;
+  }
+  const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
   child.unref();
 }
 function execCommandSync(cmd, args, options) {
@@ -1386,7 +1565,7 @@ async function processAccumulatedEventsForced(boardDir, options) {
 }
 function liveCardToTaskConfig(card) {
   const requires = card.requires;
-  const provides = card.provides ? card.provides.map((p) => p.bindTo) : [card.id];
+  const provides = card.provides?.map((p) => p.bindTo) ?? [];
   return {
     requires: requires && requires.length > 0 ? requires : void 0,
     provides,
@@ -1411,23 +1590,23 @@ function getCliInvocation(command, args) {
 }
 function invokeRunSources(boardDir, cardPath, callbackToken, callback) {
   const { cmd, args } = getCliInvocation("run-sources-internal", ["--card", cardPath, "--token", callbackToken, "--rg", boardDir]);
-  const child = process.platform === "win32" ? spawn("cmd", ["/c", "start", "/b", "", cmd, ...args], {
-    stdio: "ignore",
-    windowsHide: true
-  }) : spawn(cmd, args, {
-    shell: false,
-    detached: true,
-    stdio: "ignore"
-  });
-  let finished = false;
-  const done = (err) => {
-    if (finished) return;
-    finished = true;
-    callback(err);
-  };
-  child.on("error", (err) => done(err));
-  child.unref();
-  done(null);
+  try {
+    spawnDetachedCommand(cmd, args);
+    callback(null);
+  } catch (err) {
+    callback(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+function appendTaskExecutorLog(boardDir, hydratedSource) {
+  try {
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      hydratedSource
+    };
+    fs.appendFileSync(path.join(boardDir, TASK_EXECUTOR_LOG_FILE), JSON.stringify(entry) + "\n", "utf-8");
+  } catch (logErr) {
+    console.error(`[task-executor-log] append failed: ${logErr instanceof Error ? logErr.message : String(logErr)}`);
+  }
 }
 function invokeSourceDataFetched(sourceToken, tmpFile, callback) {
   const { cmd, args } = getCliInvocation("source-data-fetched", ["--tmp", tmpFile, "--token", sourceToken]);
@@ -1452,7 +1631,7 @@ function createBoardReactiveGraph(boardDir) {
       if (!cardPath) return "task-initiate-failure";
       const card = JSON.parse(fs.readFileSync(cardPath, "utf-8"));
       const cardId = card.id;
-      const cardState = card.state ?? {};
+      const cardState = card.card_data ?? {};
       const allSources = card.sources ?? [];
       const requiredSources = allSources.filter((s) => s.optionalForCompletionGating !== true);
       const runtime = readRuntimeState(boardDir, cardId);
@@ -1488,18 +1667,32 @@ function createBoardReactiveGraph(boardDir) {
           }
         }
       }
+      const requires = {};
+      for (const [token, taskData] of Object.entries(input.state ?? {})) {
+        if (taskData !== null && typeof taskData === "object" && !Array.isArray(taskData)) {
+          const unwrapped = taskData[token];
+          requires[token] = unwrapped !== void 0 ? unwrapped : taskData;
+        } else {
+          requires[token] = taskData;
+        }
+      }
       const computeNode = {
         id: cardId,
-        state: { ...cardState },
-        requires: input.state ?? {},
+        card_data: { ...cardState },
+        requires,
         sources: allSources,
         compute: card.compute
       };
+      computeNode._sourcesData = sourcesData;
       if (card.compute) {
         await CardCompute.run(computeNode, { sourcesData });
-        const cvPath = path.join(boardDir, `${cardId}.computed_values.json`);
-        fs.writeFileSync(cvPath, JSON.stringify(computeNode.computed_values ?? {}, null, 2));
       }
+      const cvPath = resolveComputedValuesPath(boardDir, cardId);
+      writeJsonAtomic(cvPath, {
+        schema_version: "v1",
+        card_id: cardId,
+        computed_values: computeNode.computed_values ?? {}
+      });
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const undeliveredRequired = requiredSources.filter((s) => {
         if (!s.outputFile) return false;
@@ -1519,16 +1712,40 @@ function createBoardReactiveGraph(boardDir) {
           }
         }
         if (stampedAny) writeRuntimeState(boardDir, cardId, runtime);
-        invokeRunSources(boardDir, cardPath, input.callbackToken, (err) => {
-          if (err) console.error(`[card-handler] ${input.nodeId}:`, err.message);
+        const enrichedCard = { ...card };
+        const enrichedSources = CardCompute.enrichSources(
+          Array.isArray(card.sources) ? card.sources : void 0,
+          {
+            requires,
+            sourcesData,
+            computed_values: computeNode.computed_values
+          }
+        );
+        const sourceCwd = path.dirname(cardPath);
+        enrichedCard.sources = Array.isArray(enrichedSources) ? enrichedSources.map((src) => ({
+          ...src,
+          cwd: typeof src.cwd === "string" && src.cwd ? src.cwd : sourceCwd,
+          boardDir: typeof src.boardDir === "string" && src.boardDir ? src.boardDir : boardDir
+        })) : enrichedSources;
+        const enrichedCardPath = path.join(os.tmpdir(), `card-enriched-${cardId}-${Date.now()}.json`);
+        fs.writeFileSync(enrichedCardPath, JSON.stringify(enrichedCard, null, 2), "utf-8");
+        invokeRunSources(boardDir, enrichedCardPath, input.callbackToken, (err) => {
+          if (err) {
+            console.error(`[card-handler] ${input.nodeId}:`, err.message);
+            try {
+              fs.unlinkSync(enrichedCardPath);
+            } catch {
+            }
+          }
         });
         return "task-initiated";
       }
-      const providesBindings = card.provides ?? [{ bindTo: cardId, src: `state.${cardId}` }];
+      const providesBindings = card.provides ?? [];
       const data = {};
       for (const { bindTo, src } of providesBindings) {
         data[bindTo] = CardCompute.resolve(computeNode, src);
       }
+      writeRuntimeDataObjects(boardDir, data);
       const undeliveredOptional = allSources.filter((s) => {
         if (s.optionalForCompletionGating !== true || !s.outputFile) return false;
         const entry = runtime._sources[s.bindTo];
@@ -1556,18 +1773,20 @@ function createBoardReactiveGraph(boardDir) {
 function addSingleCardFromFile(dir, cardFile) {
   const absCardPath = path.resolve(cardFile);
   if (!fs.existsSync(absCardPath)) {
-    console.error(`Card file not found: ${absCardPath}`);
-    process.exit(1);
+    throw new Error(`Card file not found: ${absCardPath}`);
+  }
+  let card;
+  try {
+    card = JSON.parse(fs.readFileSync(absCardPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`Failed to parse card file: ${absCardPath} - ${err instanceof Error ? err.message : String(err)}`);
   }
-  const card = JSON.parse(fs.readFileSync(absCardPath, "utf-8"));
   if (!card.id) {
-    console.error('Card JSON must have an "id" field');
-    process.exit(1);
+    throw new Error('Card JSON must have an "id" field');
   }
   const existing = readCardInventory(dir);
   if (existing.some((e) => e.cardId === card.id)) {
-    console.error(`Card "${card.id}" already exists in inventory`);
-    process.exit(1);
+    throw new Error(`Card "${card.id}" already exists in inventory`);
   }
   appendCardInventory(dir, {
     cardId: card.id,
@@ -1594,7 +1813,7 @@ function resolveCardGlobMatches(cardGlob) {
     unique: true,
     dot: false
   });
-  return [...matches].sort((a, b) => a.localeCompare(b));
+  return [...matches].map((m) => path.resolve(m)).sort((a, b) => a.localeCompare(b));
 }
 function cmdAddCards(args) {
   const rgIdx = args.indexOf("--rg");
@@ -1604,16 +1823,14 @@ function cmdAddCards(args) {
   const cardFile = cardIdx !== -1 ? args[cardIdx + 1] : void 0;
   const cardGlob = globIdx !== -1 ? args[globIdx + 1] : void 0;
   if (!dir || !cardFile && !cardGlob || cardFile && cardGlob) {
-    console.error("Usage: board-live-cards add-cards --rg <dir> (--card <card.json> | --card-glob <glob>)");
-    process.exit(1);
+    throw new Error("Usage: board-live-cards add-cards --rg <dir> (--card <card.json> | --card-glob <glob>)");
   }
   if (cardFile) {
     addSingleCardFromFile(dir, cardFile);
   } else {
     const matches = resolveCardGlobMatches(cardGlob);
     if (matches.length === 0) {
-      console.error(`No card files matched glob: ${cardGlob}`);
-      process.exit(1);
+      throw new Error(`No card files matched glob: ${cardGlob}`);
     }
     for (const match of matches) {
       addSingleCardFromFile(dir, match);
@@ -1625,30 +1842,34 @@ function cmdAddCards(args) {
 function cmdInit(args) {
   const dir = args[0];
   if (!dir) {
-    console.error("Usage: board-live-cards init <dir> [--task-executor <script>]");
-    process.exit(1);
+    throw new Error("Usage: board-live-cards init <dir> [--task-executor <script>] [--chat-handler <script>] [--runtime-out <dir>]");
   }
   const teIdx = args.indexOf("--task-executor");
   const taskExecutor = teIdx !== -1 ? args[teIdx + 1] : void 0;
+  const chIdx = args.indexOf("--chat-handler");
+  const chatHandler = chIdx !== -1 ? args[chIdx + 1] : void 0;
+  const roIdx = args.indexOf("--runtime-out");
+  const runtimeOut = roIdx !== -1 ? args[roIdx + 1] : void 0;
+  if (roIdx !== -1 && !runtimeOut) {
+    throw new Error("Usage: board-live-cards init <dir> [--task-executor <script>] [--chat-handler <script>] [--runtime-out <dir>]");
+  }
   const result = initBoard(dir);
   if (taskExecutor) {
     fs.writeFileSync(path.join(dir, ".task-executor"), taskExecutor, "utf-8");
   }
+  if (chatHandler) {
+    fs.writeFileSync(path.join(dir, ".chat-handler"), chatHandler, "utf-8");
+  }
+  const runtimeOutDir = configureRuntimeOutDir(dir, runtimeOut);
+  const live = loadBoard(dir);
+  writeJsonAtomic(resolveStatusSnapshotPath(dir), buildBoardStatusObject(dir, live));
   if (result === "exists") {
-    console.log(`Board already initialized at ${path.resolve(dir)}${taskExecutor ? ` (task-executor updated: ${taskExecutor})` : ""}`);
+    console.log(`Board already initialized at ${path.resolve(dir)}${taskExecutor ? ` (task-executor updated: ${taskExecutor})` : ""} (runtime-out: ${runtimeOutDir})`);
   } else {
-    console.log(`Board initialized at ${path.resolve(dir)}${taskExecutor ? ` (task-executor: ${taskExecutor})` : ""}`);
+    console.log(`Board initialized at ${path.resolve(dir)}${taskExecutor ? ` (task-executor: ${taskExecutor})` : ""} (runtime-out: ${runtimeOutDir})`);
   }
 }
-function cmdStatus(args) {
-  const rgIdx = args.indexOf("--rg");
-  const asJson = args.includes("--json");
-  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
-  if (!dir) {
-    console.error("Usage: board-live-cards status --rg <dir>");
-    process.exit(1);
-  }
-  const live = loadBoard(dir);
+function buildBoardStatusObject(dir, live) {
   const taskState = live.state.tasks;
   const taskConfig = live.config.tasks;
   const cardNames = Object.keys(taskState);
@@ -1665,14 +1886,8 @@ function cmdStatus(args) {
   for (const p of sched.pending) waitingByCard.set(p.taskName, p.waitingOn);
   for (const u of sched.unresolved) waitingByCard.set(u.taskName, u.missingTokens);
   for (const b of sched.blocked) waitingByCard.set(b.taskName, b.failedTokens);
-  const providersByToken = /* @__PURE__ */ new Map();
   const dependentsByToken = /* @__PURE__ */ new Map();
   for (const [name, cfg] of Object.entries(taskConfig)) {
-    for (const token of cfg.provides ?? []) {
-      const providers = providersByToken.get(token) ?? [];
-      providers.push(name);
-      providersByToken.set(token, providers);
-    }
     for (const token of cfg.requires ?? []) {
       const dependents = dependentsByToken.get(token) ?? [];
       dependents.push(name);
@@ -1742,7 +1957,7 @@ function cmdStatus(args) {
     const feedsAny = provides.some((p) => (dependentsByToken.get(p) ?? []).some((d) => d !== name));
     if (requiresNone && !feedsAny) orphanCards += 1;
   }
-  const statusObject = {
+  return {
     schema_version: "v1",
     meta: {
       board: {
@@ -1767,6 +1982,23 @@ function cmdStatus(args) {
     },
     cards
   };
+}
+function cmdStatus(args) {
+  const rgIdx = args.indexOf("--rg");
+  const asJson = args.includes("--json");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  if (!dir) {
+    console.error("Usage: board-live-cards status --rg <dir>");
+    process.exit(1);
+  }
+  const statusOutPath = resolveStatusSnapshotPath(dir);
+  let statusObject;
+  if (fs.existsSync(statusOutPath)) {
+    statusObject = JSON.parse(fs.readFileSync(statusOutPath, "utf-8"));
+  } else {
+    statusObject = buildBoardStatusObject(dir, loadBoard(dir));
+    writeJsonAtomic(statusOutPath, statusObject);
+  }
   if (asJson) {
     console.log(JSON.stringify(statusObject, null, 2));
     return;
@@ -1797,6 +2029,7 @@ function cmdTaskCompleted(args) {
     process.exit(1);
   }
   const data = dataIdx !== -1 ? JSON.parse(args[dataIdx + 1]) : {};
+  writeRuntimeDataObjects(dir, data);
   appendEventToJournal(dir, {
     type: "task-completed",
     taskName: decoded.taskName,
@@ -1923,6 +2156,12 @@ function cmdRunSources(args) {
     process.exit(1);
   }
   const card = JSON.parse(fs.readFileSync(cardFilePath, "utf-8"));
+  if (path.basename(cardFilePath).startsWith("card-enriched-")) {
+    try {
+      fs.unlinkSync(cardFilePath);
+    } catch {
+    }
+  }
   console.log(`[run-sources-internal] Processing card "${card.id}"`);
   const executorFile = path.join(boardDir, ".task-executor");
   const taskExecutor = fs.existsSync(executorFile) ? fs.readFileSync(executorFile, "utf-8").trim() : void 0;
@@ -1951,7 +2190,12 @@ function cmdRunSources(args) {
       const inFile = path.join(os.tmpdir(), `card-source-in-${src.bindTo}-${Date.now()}.json`);
       const outFile2 = path.join(os.tmpdir(), `card-source-out-${src.bindTo}-${Date.now()}.json`);
       const errFile = path.join(os.tmpdir(), `card-source-err-${src.bindTo}-${Date.now()}.txt`);
-      const sourceForExecutor = { ...src, cwd: path.dirname(cardFilePath || ""), boardDir };
+      const sourceForExecutor = {
+        ...src,
+        cwd: typeof src.cwd === "string" && src.cwd ? src.cwd : path.dirname(cardFilePath || ""),
+        boardDir: typeof src.boardDir === "string" && src.boardDir ? src.boardDir : boardDir
+      };
+      appendTaskExecutorLog(boardDir, sourceForExecutor);
       fs.writeFileSync(inFile, JSON.stringify(sourceForExecutor, null, 2), "utf-8");
       console.log(`[run-sources-internal] task-executor: ${taskExecutor} run-source-fetch --in ${inFile} --out ${outFile2} --err ${errFile}`);
       try {
@@ -2108,17 +2352,14 @@ function cmdUpdateCard(args) {
   const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
   const cardId = idIdx !== -1 ? args[idIdx + 1] : void 0;
   if (!dir || !cardId) {
-    console.error("Usage: board-live-cards update-card --rg <dir> --card-id <card-id> [--restart]");
-    process.exit(1);
+    throw new Error("Usage: board-live-cards update-card --rg <dir> --card-id <card-id> [--restart]");
   }
   const cardPath = lookupCardPath(dir, cardId);
   if (!cardPath) {
-    console.error(`Card "${cardId}" not found in inventory`);
-    process.exit(1);
+    throw new Error(`Card "${cardId}" not found in inventory`);
   }
   if (!fs.existsSync(cardPath)) {
-    console.error(`Card file not found: ${cardPath}`);
-    process.exit(1);
+    throw new Error(`Card file not found: ${cardPath}`);
   }
   const card = JSON.parse(fs.readFileSync(cardPath, "utf-8"));
   const taskConfig = liveCardToTaskConfig(card);
@@ -2138,6 +2379,121 @@ function cmdUpdateCard(args) {
   void processAccumulatedEventsInfinitePass(dir);
   console.log(`Card "${cardId}" updated${restart ? " (restarted)" : ""}.`);
 }
+function cmdUpsertCard(args) {
+  const rgIdx = args.indexOf("--rg");
+  const cardIdx = args.indexOf("--card");
+  const globIdx = args.indexOf("--card-glob");
+  const cardIdIdx = args.indexOf("--card-id");
+  const restart = args.includes("--restart");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const cardFile = cardIdx !== -1 ? args[cardIdx + 1] : void 0;
+  const cardGlob = globIdx !== -1 ? args[globIdx + 1] : void 0;
+  const requestedCardId = cardIdIdx !== -1 ? args[cardIdIdx + 1] : void 0;
+  if (!dir || !cardFile && !cardGlob || cardFile && cardGlob) {
+    console.error("Usage: board-live-cards upsert-card --rg <dir> (--card <card.json> | --card-glob <glob>) [--card-id <card-id>] [--restart]");
+    process.exit(1);
+  }
+  if (cardGlob && requestedCardId) {
+    console.error("Usage: --card-id may be used only with --card (single file), not with --card-glob");
+    process.exit(1);
+  }
+  const cardFiles = cardFile ? [path.resolve(cardFile)] : resolveCardGlobMatches(cardGlob);
+  if (!cardFile && cardFiles.length === 0) {
+    console.error(`No card files matched glob: ${cardGlob}`);
+    process.exit(1);
+  }
+  const idx = buildCardInventoryIndex(dir);
+  const batchByCardId = /* @__PURE__ */ new Map();
+  const batchByCardPath = /* @__PURE__ */ new Map();
+  const plans = [];
+  const logs = [];
+  for (const absCardPath of cardFiles) {
+    if (!fs.existsSync(absCardPath)) {
+      console.error(`Card file not found: ${absCardPath}`);
+      process.exit(1);
+    }
+    const card = JSON.parse(fs.readFileSync(absCardPath, "utf-8"));
+    if (!card.id) {
+      console.error(`Card JSON must have an "id" field (${absCardPath})`);
+      process.exit(1);
+    }
+    if (requestedCardId && requestedCardId !== card.id) {
+      console.error(
+        `Card id mismatch: --card-id "${requestedCardId}" does not match file id "${card.id}" (${absCardPath})`
+      );
+      process.exit(1);
+    }
+    const seenPathCardId = batchByCardPath.get(absCardPath);
+    if (seenPathCardId && seenPathCardId !== card.id) {
+      console.error(
+        `Upsert rejected: file "${absCardPath}" appears multiple times in batch with conflicting ids ("${seenPathCardId}" vs "${card.id}")`
+      );
+      process.exit(1);
+    }
+    const seenCardPath = batchByCardId.get(card.id);
+    if (seenCardPath && seenCardPath !== absCardPath) {
+      console.error(
+        `Upsert rejected: card id "${card.id}" appears multiple times in batch with conflicting files ("${seenCardPath}" vs "${absCardPath}")`
+      );
+      process.exit(1);
+    }
+    const existingById = idx.byCardId.get(card.id);
+    const existingByPath = idx.byCardPath.get(absCardPath);
+    if (existingByPath && existingByPath.cardId !== card.id) {
+      console.error(
+        `Upsert rejected: file "${absCardPath}" is already mapped to card id "${existingByPath.cardId}", cannot remap to "${card.id}"`
+      );
+      process.exit(1);
+    }
+    if (existingById && existingById.cardFilePath !== absCardPath) {
+      console.error(
+        `Upsert rejected: card id "${card.id}" is already mapped to file "${existingById.cardFilePath}", cannot remap to "${absCardPath}"`
+      );
+      process.exit(1);
+    }
+    batchByCardPath.set(absCardPath, card.id);
+    batchByCardId.set(card.id, absCardPath);
+    plans.push({
+      card,
+      absCardPath,
+      isInsert: !existingById
+    });
+  }
+  for (const plan of plans) {
+    const { card, absCardPath, isInsert } = plan;
+    if (isInsert) {
+      const newEntry = {
+        cardId: card.id,
+        cardFilePath: absCardPath,
+        addedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      appendCardInventory(dir, newEntry);
+      idx.byCardId.set(card.id, newEntry);
+      idx.byCardPath.set(absCardPath, newEntry);
+    }
+    const taskConfig = liveCardToTaskConfig(card);
+    appendEventToJournal(dir, {
+      type: "task-upsert",
+      taskName: card.id,
+      taskConfig,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (restart) {
+      appendEventToJournal(dir, {
+        type: "task-restart",
+        taskName: card.id,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    logs.push(`Card "${card.id}" ${isInsert ? "upserted (inserted)" : "upserted (updated)"}${restart ? " (restarted)" : ""}.`);
+  }
+  void processAccumulatedEventsInfinitePass(dir);
+  if (cardGlob) {
+    console.log(`Upserted ${cardFiles.length} cards from glob: ${cardGlob}${restart ? " (restarted)" : ""}`);
+  } else {
+    console.log(logs[0]);
+  }
+}
 async function cmdTryDrain(args) {
   const rgIdx = args.indexOf("--rg");
   const inlineLoop = args.includes("--inline-loop");
@@ -2181,6 +2537,8 @@ async function cli(argv) {
       return cmdAddCards(rest);
     case "update-card":
       return cmdUpdateCard(rest);
+    case "upsert-card":
+      return cmdUpsertCard(rest);
     case "remove-card":
       return cmdRemoveCard(rest);
     case "retrigger":
@@ -2200,9 +2558,7 @@ async function cli(argv) {
     case "process-accumulated-events":
       return await cmdTryDrain(rest);
     default:
-      console.error(`Unknown command: ${cmd ?? "(none)"}`);
-      console.error("Run: board-live-cards help");
-      process.exit(1);
+      throw new Error(`Unknown command: ${cmd ?? "(none)"}`);
   }
 }
 function cmdHelp() {
@@ -2213,14 +2569,18 @@ USAGE
   board-live-cards-cli <command> [options]
 
 BOARD MANAGEMENT
-  init <dir> [--task-executor <script>]
+  init <dir> [--task-executor <script>] [--runtime-out <dir>]
     Create a new board in <dir>.
     If --task-executor is given, writes <dir>/.task-executor with the script path.
+    Writes <dir>/.runtime-out (default: <dir>/runtime-out).
+    Published runtime files:
+      <runtime-out>/board-livegraph-status.json
+      <runtime-out>/cards/<card-id>.computed.json
     Re-running init on an existing board is safe; --task-executor updates the registration.
 
   status --rg <dir> [--json]
-    Print the current task status of every card in the board.
-    --json emits a stable machine-readable status object.
+    Read and print the published status snapshot from <runtime-out>/board-livegraph-status.json.
+    --json emits the stable machine-readable status object.
 
 CARD MANAGEMENT
   add-cards --rg <dir> (--card <card.json> | --card-glob <glob>)
@@ -2233,6 +2593,16 @@ CARD MANAGEMENT
     Re-read the card JSON from disk and patch the board.
     --restart clears the task so it re-triggers from scratch.
 
+  upsert-card --rg <dir> (--card <card.json> | --card-glob <glob>) [--card-id <card-id>] [--restart]
+    Insert or update one or many cards.
+    Enforces strict one-to-one mapping between card id and file path:
+      - same id + same file path: update
+      - new id + new file path: insert
+      - id remap or file remap: rejected
+    If --card-id is provided, it must match the id inside the file.
+    --card-id is valid only with --card (single file), not with --card-glob.
+    --restart clears the task so it re-triggers from scratch.
+
   remove-card --rg <dir> --id <card-id>
     Remove a card and its task from the board.
 
@@ -2327,6 +2697,6 @@ if (isMain) {
   });
 }
 
-export { BoardJournal, appendCardInventory, appendEventToJournal, cli, createBoardReactiveGraph, decodeSourceToken, encodeSourceToken, getUndrainedEntries, initBoard, liveCardToTaskConfig, loadBoard, loadBoardEnvelope, lookupCardPath, processAccumulatedEvents, processAccumulatedEventsForced, processAccumulatedEventsInfinitePass, readCardInventory, saveBoard, withBoardLock };
+export { BoardJournal, appendCardInventory, appendEventToJournal, buildCardInventoryIndex, cli, createBoardReactiveGraph, decodeSourceToken, encodeSourceToken, getUndrainedEntries, initBoard, liveCardToTaskConfig, loadBoard, loadBoardEnvelope, lookupCardPath, processAccumulatedEvents, processAccumulatedEventsForced, processAccumulatedEventsInfinitePass, readCardInventory, saveBoard, withBoardLock };
 //# sourceMappingURL=board-live-cards-cli.js.map
 //# sourceMappingURL=board-live-cards-cli.js.map