yaml-flow 5.2.6 → 5.2.8

package/dist/{live-cards-bridge-CeNxiVcm.d.ts → live-cards-bridge-EQjytzI_.d.ts}

@@ -152,8 +152,13 @@ interface ReactiveGraph {
     getState(): LiveGraph;
     /** Current schedule projection. */
     getSchedule(): ScheduleResult;
-    /** Stop accepting events. */
-    dispose(): void;
+    /**
+     * Stop accepting events.
+     * @param options.wait — if true, await all in-flight handler promises before marking disposed.
+     */
+    dispose(options?: {
+        wait?: boolean;
+    }): Promise<void>;
 }
 declare function createReactiveGraph(configOrLive: GraphConfig | LiveGraph, options: ReactiveGraphOptions, executionId?: string): ReactiveGraph;
 
@@ -179,7 +184,7 @@ declare function createReactiveGraph(configOrLive: GraphConfig | LiveGraph, opti
  * import { liveCardsToReactiveGraph } from 'yaml-flow/continuous-event-graph';
  *
  * const cards = [
- *   { id: 'prices', sources: [{ kind: 'api', bindTo: 'raw' }], state: {} },
+ *   { id: 'prices', source_defs: [{ kind: 'api', bindTo: 'raw' }], state: {} },
  *   { id: 'dashboard', requires: ['prices'], state: {}, compute: [{ bindTo: 'total', fn: 'sum', ... }], view: { ... } },
  * ];
  *
@@ -201,7 +206,7 @@ declare function createReactiveGraph(configOrLive: GraphConfig | LiveGraph, opti
 /** A provides binding: maps a token name to a source path in the card's data namespace. */
 interface ProvidesBinding {
     bindTo: string;
-    src: string;
+    ref: string;
 }
 interface LiveCard {
     id: string;
@@ -217,7 +222,7 @@ interface LiveCard {
         fn: string;
         [key: string]: unknown;
     }[];
-    sources?: {
+    source_defs?: {
         cli?: string;
         bindTo: string;
         outputFile: string;

package/dist/{live-cards-bridge-z_rJCSbi.d.cts → live-cards-bridge-x5XREkXm.d.cts}

@@ -152,8 +152,13 @@ interface ReactiveGraph {
     getState(): LiveGraph;
     /** Current schedule projection. */
     getSchedule(): ScheduleResult;
-    /** Stop accepting events. */
-    dispose(): void;
+    /**
+     * Stop accepting events.
+     * @param options.wait — if true, await all in-flight handler promises before marking disposed.
+     */
+    dispose(options?: {
+        wait?: boolean;
+    }): Promise<void>;
 }
 declare function createReactiveGraph(configOrLive: GraphConfig | LiveGraph, options: ReactiveGraphOptions, executionId?: string): ReactiveGraph;
 
@@ -179,7 +184,7 @@ declare function createReactiveGraph(configOrLive: GraphConfig | LiveGraph, opti
  * import { liveCardsToReactiveGraph } from 'yaml-flow/continuous-event-graph';
  *
  * const cards = [
- *   { id: 'prices', sources: [{ kind: 'api', bindTo: 'raw' }], state: {} },
+ *   { id: 'prices', source_defs: [{ kind: 'api', bindTo: 'raw' }], state: {} },
  *   { id: 'dashboard', requires: ['prices'], state: {}, compute: [{ bindTo: 'total', fn: 'sum', ... }], view: { ... } },
  * ];
  *
@@ -201,7 +206,7 @@ declare function createReactiveGraph(configOrLive: GraphConfig | LiveGraph, opti
 /** A provides binding: maps a token name to a source path in the card's data namespace. */
 interface ProvidesBinding {
     bindTo: string;
-    src: string;
+    ref: string;
 }
 interface LiveCard {
     id: string;
@@ -217,7 +222,7 @@ interface LiveCard {
         fn: string;
         [key: string]: unknown;
     }[];
-    sources?: {
+    source_defs?: {
         cli?: string;
         bindTo: string;
         outputFile: string;

package/examples/browser/boards/portfolio-tracker/cards/holdings-table.json

@@ -2,7 +2,7 @@
   "id": "holdings-table",
   "meta": { "title": "Holdings Table" },
   "requires": ["holdings", "prices"],
-  "provides": [{ "bindTo": "table", "src": "computed_values.table" }],
+  "provides": [{ "bindTo": "table", "ref": "computed_values.table" }],
   "card_data": {},
   "compute": [
     {

package/examples/browser/boards/portfolio-tracker/cards/portfolio-form.json

@@ -1,7 +1,7 @@
 {
   "id": "portfolio-form",
   "meta": { "title": "Portfolio Holdings Form" },
-  "provides": [{ "bindTo": "holdings", "src": "card_data.holdings" }],
+  "provides": [{ "bindTo": "holdings", "ref": "card_data.holdings" }],
   "card_data": {
     "holdings": [
       { "symbol": "AAPL", "qty": 50 },

package/examples/browser/boards/portfolio-tracker/cards/portfolio-risk-assessment.json

@@ -3,7 +3,7 @@
   "meta": { "title": "Portfolio Risk Assessment" },
   "requires": ["table", "totalValue"],
   "provides": [
-    { "bindTo": "riskAssessment", "src": "card_data.llm_task_completion_inference.reason" }
+    { "bindTo": "riskAssessment", "ref": "card_data.llm_task_completion_inference.reason" }
   ],
   "card_data": {
     "llm_task_completion_inference": {

package/examples/browser/boards/portfolio-tracker/cards/portfolio-value.json

@@ -2,7 +2,7 @@
   "id": "portfolio-value",
   "meta": { "title": "Portfolio Total Value" },
   "requires": ["table"],
-  "provides": [{ "bindTo": "totalValue", "src": "computed_values.totalValue" }],
+  "provides": [{ "bindTo": "totalValue", "ref": "computed_values.totalValue" }],
   "card_data": {},
   "compute": [
     { "bindTo": "totalValue", "expr": "$sum(requires.table.rows.value)" }

package/examples/browser/boards/portfolio-tracker/cards/price-fetch.json

@@ -2,9 +2,9 @@
   "id": "price-fetch",
   "meta": { "title": "Fetch Market Prices" },
   "requires": ["holdings"],
-  "provides": [{ "bindTo": "prices", "src": "fetched_sources.prices" }],
+  "provides": [{ "bindTo": "prices", "ref": "fetched_sources.prices" }],
   "card_data": {},
-  "sources": [
+  "source_defs": [
     { "cli": "node ../fetch-prices.js", "bindTo": "prices", "outputFile": "prices.json" }
   ],
   "view": {

package/examples/browser/boards/portfolio-tracker/cards/rebalancing-strategy.json

@@ -3,7 +3,7 @@
   "meta": { "title": "Rebalancing Strategy" },
   "requires": ["table", "totalValue", "riskAssessment"],
   "provides": [
-    { "bindTo": "rebalancingPlan", "src": "card_data.llm_task_completion_inference.reason" }
+    { "bindTo": "rebalancingPlan", "ref": "card_data.llm_task_completion_inference.reason" }
   ],
   "card_data": {
     "llm_task_completion_inference": {

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

@@ -201,9 +201,9 @@ function printTaskExecutorLog() {
   } else {
     cli('init', BOARD, '--inference-adapter', INFERENCE_ADAPTER);
   }
-  cli('add-cards', '--rg', BOARD, '--card-glob', path.join(CARDS, '*.json'));
+  cli('upsert-card', '--rg', BOARD, '--card-glob', path.join(CARDS, '*.json'));
 
-  console.log('\n--- T0 Status (after add-cards) ---');
+  console.log('\n--- T0 Status (after upsert-card) ---');
   process.stdout.write(statusText());
 
   console.log('\n=== T1: Writing market prices ===');
@@ -219,7 +219,7 @@ function printTaskExecutorLog() {
   const portfolioFormV2 = {
     id: 'portfolio-form',
     meta: { title: 'Portfolio Holdings Form' },
-    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    provides: [{ bindTo: 'holdings', ref: 'card_data.holdings' }],
     card_data: {
       holdings: [
         { symbol: 'AAPL', qty: 50 },
@@ -235,7 +235,7 @@ function printTaskExecutorLog() {
   };
   fs.writeFileSync(portfolioFormPath, JSON.stringify(portfolioFormV2, null, 2));
 
-  cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
+  cli('upsert-card', '--rg', BOARD, '--card', portfolioFormPath, '--restart');
   await sleep(500);
   writePrices({ AAPL: 198.50, MSFT: 425.30, GOOG: 178.90, AMZN: 192.40, TSLA: 168.75 });
   releaseInferenceAdapters('T2');
@@ -260,7 +260,7 @@ function printTaskExecutorLog() {
   const portfolioFormV3 = {
     id: 'portfolio-form',
     meta: { title: 'Portfolio Holdings Form' },
-    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    provides: [{ bindTo: 'holdings', ref: 'card_data.holdings' }],
     card_data: {
       holdings: [
         { symbol: 'AAPL', qty: 50 },
@@ -279,7 +279,7 @@ function printTaskExecutorLog() {
   const portfolioFormV4 = {
     id: 'portfolio-form',
     meta: { title: 'Portfolio Holdings Form' },
-    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    provides: [{ bindTo: 'holdings', ref: 'card_data.holdings' }],
     card_data: {
       holdings: [
         { symbol: 'AAPL', qty: 45 },
@@ -298,7 +298,7 @@ function printTaskExecutorLog() {
   const portfolioFormV5 = {
     id: 'portfolio-form',
     meta: { title: 'Portfolio Holdings Form' },
-    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    provides: [{ bindTo: 'holdings', ref: 'card_data.holdings' }],
     card_data: {
       holdings: [
         { symbol: 'AAPL', qty: 40 },
@@ -316,15 +316,15 @@ function printTaskExecutorLog() {
 
   // First update starts a source fetch request.
   fs.writeFileSync(portfolioFormPath, JSON.stringify(portfolioFormV3, null, 2));
-  cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
+  cli('upsert-card', '--rg', BOARD, '--card', portfolioFormPath, '--restart');
 
   // Immediate second update should queue a newer checksum while the first request is in-flight.
   fs.writeFileSync(portfolioFormPath, JSON.stringify(portfolioFormV4, null, 2));
-  cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
+  cli('upsert-card', '--rg', BOARD, '--card', portfolioFormPath, '--restart');
 
   // Immediate third update should overwrite queued checksum (latest-state wins).
   fs.writeFileSync(portfolioFormPath, JSON.stringify(portfolioFormV5, null, 2));
-  cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
+  cli('upsert-card', '--rg', BOARD, '--card', portfolioFormPath, '--restart');
 
   // 7) wait for first request, then 8) write response prices for update #1 tickers.
   // await readFetchRequest('T4 first fetch', ['AAPL', 'MSFT', 'GOOG', 'AMZN']);

package/examples/cli/step-machine-cli/portfolio-tracker/cards/holdings-table.json

@@ -2,7 +2,7 @@
   "id": "holdings-table",
   "meta": { "title": "Holdings Table" },
   "requires": ["holdings", "prices"],
-  "provides": [{ "bindTo": "table", "src": "computed_values.table" }],
+  "provides": [{ "bindTo": "table", "ref": "computed_values.table" }],
   "card_data": {},
   "compute": [
     {

package/examples/cli/step-machine-cli/portfolio-tracker/cards/portfolio-form.json

@@ -6,7 +6,7 @@
   "provides": [
     {
       "bindTo": "holdings",
-      "src": "card_data.holdings"
+      "ref": "card_data.holdings"
     }
   ],
   "card_data": {

package/examples/cli/step-machine-cli/portfolio-tracker/cards/portfolio-value.json

@@ -2,7 +2,7 @@
   "id": "portfolio-value",
   "meta": { "title": "Portfolio Total Value" },
   "requires": ["table"],
-  "provides": [{ "bindTo": "totalValue", "src": "computed_values.totalValue" }],
+  "provides": [{ "bindTo": "totalValue", "ref": "computed_values.totalValue" }],
   "card_data": {},
   "compute": [
     { "bindTo": "totalValue", "expr": "$sum(requires.table.rows.value)" }

package/examples/cli/step-machine-cli/portfolio-tracker/cards/price-fetch.json

@@ -2,9 +2,9 @@
   "id": "price-fetch",
   "meta": { "title": "Fetch Market Prices" },
   "requires": ["holdings"],
-  "provides": [{ "bindTo": "prices", "src": "fetched_sources.prices" }],
+  "provides": [{ "bindTo": "prices", "ref": "fetched_sources.prices" }],
   "card_data": {},
-  "sources": [
+  "source_defs": [
     { "cli": "node ../fetch-prices.js --tmp-file-name tmp_file1", "bindTo": "prices", "outputFile": "prices.json" }
   ],
   "view": {

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/add-cards-cli.js

@@ -12,7 +12,7 @@ try {
     process.exit(0);
   }
 
-  runBoardCli(['add-cards', '--rg', boardDir, '--card-glob', cardsGlob]);
+  runBoardCli(['upsert-card', '--rg', boardDir, '--card-glob', cardsGlob]);
 
   writeResult({
     result: 'success',

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/update-holdings-cli.js

@@ -22,7 +22,7 @@ try {
   card.card_data.holdings = holdings;
   fs.writeFileSync(cardPath, `${JSON.stringify(card, null, 2)}\n`, 'utf-8');
 
-  runBoardCli(['update-card', '--rg', boardDir, '--card-id', 'portfolio-form', '--restart']);
+  runBoardCli(['upsert-card', '--rg', boardDir, '--card', cardPath, '--restart']);
 
   writeResult({
     result: 'success',

package/examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml

@@ -44,7 +44,7 @@ steps:
     expects_data: [board_dir, cards_template_dir]
     produces_data: [cards_dir]
     handler:
-      cli: node %%BOARDCLI_CMD%% add-cards --rg "%%BOARD_DIR%%" --card-glob "%%CARDS_GLOB%%"
+      cli: node %%BOARDCLI_CMD%% upsert-card --rg "%%BOARD_DIR%%" --card-glob "%%CARDS_GLOB%%"
       result-mode: exit-code
       input-transforms:
         BOARD_DIR: board_dir

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

@@ -9,7 +9,7 @@
 - **No redundancy across cards** — each column on a board should appear on exactly one card. If a value is already visible elsewhere, omit it; the user's eye can join cards mentally.
 - **Aggregations are distinct** — a metric that summarises data from another card (total, count, average) is not redundant — it is new information. Keep it.
 - **Separate input from output** — cards with editable elements (`editable-table`, `form`, `filter`) should stay lean; put heavy compute and display in a separate downstream card that `requires` the published token.
-- **Propagate data, not display** — use `provides` to pass data between cards; never duplicate a `sources[]` fetch for data another card already provides.
+- **Propagate data, not display** — use `provides` to pass data between cards; never duplicate a `source_defs[]` fetch for data another card already provides.
 - **KISS** — if you are unsure whether a field adds value, leave it out. A sparse card that is immediately readable is better than a dense card that requires study.
 
 ---