yaml-flow 3.1.1 → 5.0.0

package/README.md

@@ -9,6 +9,66 @@ Two workflow engines in one package. Pick the model that fits your problem.
 npm install yaml-flow
 ```
 
+## Public Surfaces
+
+yaml-flow is not only a low-level npm library. It exposes three practical consumption surfaces:
+
+1. **Library APIs**
+  Use the package imports when you want to embed workflow logic directly in your application.
+  The primary library APIs are `yaml-flow/step-machine`, `yaml-flow/continuous-event-graph`, and `yaml-flow/inference`.
+  `yaml-flow/batch` is also available as a convenience utility for concurrent processing of item collections using Step Machine, Live Event Graph, or graph-of-graphs execution patterns.
+
+2. **Live-Cards / Boards Package Layer**
+  This is a reusable higher-level package pattern built from yaml-flow engines, schemas, browser runtime assets, and CLI orchestration.
+  It includes:
+  - `board-live-cards-cli`
+  - browser runtime assets under `browser/`
+  - `yaml-flow/card-compute`
+
+3. **Step-machine CLI**
+  `step-machine-cli` is the standalone operational runner for YAML step-machine workflows with inline handlers, CLI handlers, and JSONata transforms.
+  For durable and operator-controlled runs, use `--store file --store-dir ...` plus `--pause`, `--resume`, and `--status`.
+
+## Documentation Map
+
+- Main orientation: `README.md`
+- Runnable examples: `examples/index.html`
+- Docs landing page: `docs/index.html`
+- Board live-cards CLI reference: `docs/board-live-cards-cli.html`
+- Step-machine CLI reference: `docs/step-machine-cli.html`
+- Browser runtime guide: `docs/browser-runtime-livecards-boards.html`
+- Schemas: `schema/` and `browser/live-cards.schema.json`
+
+## Repository Organization
+
+- `dist/` contains the built library output.
+- `schema/` contains public config and contract schemas.
+- `browser/` contains shipped browser-consumable runtime assets.
+- `examples/` contains runnable examples for the public surfaces.
+- `docs/` contains deeper reference and design material for repo/GitHub readers.
+- `app/` is best treated as demo/showcase code, not as the primary public documentation surface.
+
+## Board Live Cards CLI (Canonical External Path)
+
+When installed from npm, use the package-exposed command:
+
+```bash
+npx board-live-cards-cli --help
+```
+
+If installed as a dependency in another project, invoke it the same way via your package runner:
+
+```bash
+board-live-cards-cli --help
+```
+
+This is the canonical black-box entrypoint for external usage.
+
+Command reference: `docs/board-live-cards-cli.html`
+Status JSON schema: `schema/board-status.schema.json`
+
+Step-machine CLI reference: `docs/step-machine-cli.html`
+
 ## Which Mode Do I Need?
 
 yaml-flow ships two execution models. They solve fundamentally different problems.
@@ -152,6 +212,7 @@ const result = await machine.run({ message: 'I was double-charged' });
 | Feature | Config |
 |---|---|
 | Transitions | `transitions: { success: next_step, failure: error_step }` |
+| Failure transitions | `failure_transitions: { failure: error_step, timeout: timeout_step }` |
 | Retry | `retry: { max_attempts: 3, delay_ms: 1000, backoff_multiplier: 2 }` |
 | Circuit breaker | `circuit_breaker: { max_iterations: 5, on_open: fallback }` |
 | Pause / resume | `await machine.pause(runId)` / `await machine.resume(runId)` |
@@ -790,7 +851,7 @@ while (true) {
 - Every deployment customizes how sub-tasks execute: in-process, `execSync`, HTTP, serverless.
 - The primitives (`batch` + `resolveVariables` + `resolveConfigTemplates` + both engines) compose without coupling.
 
-See the [examples/graph-of-graphs/](./examples/graph-of-graphs/) directory for complete runnable examples.
+See the [examples/npm-libs/graph-of-graphs/](./examples/npm-libs/graph-of-graphs/) directory for complete runnable examples.
 
 ---
 
@@ -1494,25 +1555,25 @@ See the [examples/](./examples) directory:
 
 | Example | Mode | Demonstrates |
 |---|---|---|
-| [Simple Greeting](./examples/node/simple-greeting.ts) | Step Machine | Basic flow with file store |
-| [AI Conversation](./examples/node/ai-conversation.ts) | Step Machine | Retry, circuit breakers, component injection |
-| [Research Pipeline](./examples/event-graph/research-pipeline.ts) | Event Graph | Parallel tasks, goal-based completion |
-| [CI/CD Pipeline](./examples/event-graph/ci-cd-pipeline.ts) | Event Graph | External events, conditional routing, failure tokens |
-| [Batch Tickets](./examples/batch/batch-step-machine.ts) | Batch | Concurrent processing, progress tracking |
-| [URL Pipeline](./examples/graph-of-graphs/url-processing-pipeline.ts) | Graph-of-Graphs | Outer event-graph → batch × inner event-graph per item |
-| [Multi-Stage ETL](./examples/graph-of-graphs/multi-stage-etl.ts) | Graph-of-Graphs | Mixed modes: event-graph outer → step-machine + event-graph subs |
-| [Stock Dashboard](./examples/continuous-event-graph/stock-dashboard.ts) | Continuous Event Graph | Runtime mutations, token drain, upstream/downstream, snapshot |
-| [Reactive Pipeline](./examples/continuous-event-graph/reactive-pipeline.ts) | Reactive Graph | Self-driving ETL — push once, 4 tasks complete automatically |
-| [Reactive Monitoring](./examples/continuous-event-graph/reactive-monitoring.ts) | Reactive Graph | Conditional routing, on_failure escalation, runtime addNode |
-| [Live Portfolio Dashboard](./examples/continuous-event-graph/live-portfolio-dashboard.ts) | Reactive Graph + Live Cards | 15+ cards, disk roundtrip, addRequires/removeRequires, addProvides/removeProvides, pushAll, retriggerAll |
-| [Executor Pipeline](./examples/event-graph/executor-pipeline.ts) | Event Graph (library) | You-drive-the-loop ETL with random async delays |
-| [Executor Diamond](./examples/event-graph/executor-diamond.ts) | Event Graph (library) | Parallel fan-out/fan-in diamond DAG with async executors |
-| [Azure Deployment](./examples/inference/azure-deployment.ts) | Inference | LLM analyzes deployment logs, auto-completes checkpoints |
-| [Data Pipeline](./examples/inference/data-pipeline.ts) | Inference | Iterative inference — evidence arrives in waves |
-| [Pluggable Adapters](./examples/inference/pluggable-adapters.ts) | Inference | OpenAI, Anthropic, Azure, CLI, HTTP adapter factories |
-| [Copilot CLI](./examples/inference/copilot-cli.ts) | Inference | GitHub Copilot CLI as inference adapter via `createCliAdapter` |
-| [Order Processing](./examples/flows/order-processing.yaml) | Step Machine | YAML flow definition |
-| [Browser Demo](./examples/browser/index.html) | Step Machine | In-browser usage |
+| [Simple Greeting](./examples/npm-libs/node/simple-greeting.ts) | Step Machine | Basic flow with file store |
+| [AI Conversation](./examples/npm-libs/node/ai-conversation.ts) | Step Machine | Retry, circuit breakers, component injection |
+| [Research Pipeline](./examples/npm-libs/event-graph/research-pipeline.ts) | Event Graph | Parallel tasks, goal-based completion |
+| [CI/CD Pipeline](./examples/npm-libs/event-graph/ci-cd-pipeline.ts) | Event Graph | External events, conditional routing, failure tokens |
+| [Batch Tickets](./examples/npm-libs/batch/batch-step-machine.ts) | Batch | Concurrent processing, progress tracking |
+| [URL Pipeline](./examples/npm-libs/graph-of-graphs/url-processing-pipeline.ts) | Graph-of-Graphs | Outer event-graph → batch × inner event-graph per item |
+| [Multi-Stage ETL](./examples/npm-libs/graph-of-graphs/multi-stage-etl.ts) | Graph-of-Graphs | Mixed modes: event-graph outer → step-machine + event-graph subs |
+| [Stock Dashboard](./examples/npm-libs/continuous-event-graph/stock-dashboard.ts) | Continuous Event Graph | Runtime mutations, token drain, upstream/downstream, snapshot |
+| [Reactive Pipeline](./examples/npm-libs/continuous-event-graph/reactive-pipeline.ts) | Reactive Graph | Self-driving ETL — push once, 4 tasks complete automatically |
+| [Reactive Monitoring](./examples/npm-libs/continuous-event-graph/reactive-monitoring.ts) | Reactive Graph | Conditional routing, on_failure escalation, runtime addNode |
+| [Live Portfolio Dashboard](./examples/npm-libs/continuous-event-graph/live-portfolio-dashboard.ts) | Reactive Graph + Live Cards | 15+ cards, disk roundtrip, addRequires/removeRequires, addProvides/removeProvides, pushAll, retriggerAll |
+| [Executor Pipeline](./examples/npm-libs/event-graph/executor-pipeline.ts) | Event Graph (library) | You-drive-the-loop ETL with random async delays |
+| [Executor Diamond](./examples/npm-libs/event-graph/executor-diamond.ts) | Event Graph (library) | Parallel fan-out/fan-in diamond DAG with async executors |
+| [Azure Deployment](./examples/npm-libs/inference/azure-deployment.ts) | Inference | LLM analyzes deployment logs, auto-completes checkpoints |
+| [Data Pipeline](./examples/npm-libs/inference/data-pipeline.ts) | Inference | Iterative inference — evidence arrives in waves |
+| [Pluggable Adapters](./examples/npm-libs/inference/pluggable-adapters.ts) | Inference | OpenAI, Anthropic, Azure, CLI, HTTP adapter factories |
+| [Copilot CLI](./examples/npm-libs/inference/copilot-cli.ts) | Inference | GitHub Copilot CLI as inference adapter via `createCliAdapter` |
+| [Order Processing](./examples/npm-libs/flows/order-processing.yaml) | Step Machine | YAML flow definition |
+| [Browser Demo](./examples/browser/step-machine-browser/index.html) | Step Machine | In-browser usage |
 
 ---
 

package/board-live-cards-cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const distCli = path.join(__dirname, 'dist', 'cli', 'board-live-cards-cli.js');
+const srcCli = path.join(__dirname, 'src', 'cli', 'board-live-cards-cli.ts');
+const tsxCli = path.join(__dirname, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+
+if (fs.existsSync(distCli)) {
+  const { cli } = await import(pathToFileUrl(distCli).href);
+  await cli(process.argv.slice(2));
+} else if (fs.existsSync(srcCli)) {
+  const result = spawnSync(process.execPath, [tsxCli, srcCli, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    shell: false,
+    windowsHide: true,
+  });
+
+  if (result.error) {
+    console.error(`[board-live-cards-cli] Failed to launch dev fallback: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  process.exit(result.status ?? 0);
+} else {
+  console.error('[board-live-cards-cli] Could not find dist or src CLI entrypoint.');
+  process.exit(1);
+}
+
+function pathToFileUrl(filePath) {
+  const resolved = path.resolve(filePath).replace(/\\/g, '/');
+  return new URL(`file:///${resolved.startsWith('/') ? resolved.slice(1) : resolved}`);
+}