yaml-flow 3.1.0 → 4.0.0

package/dist/cli/board-live-cards-cli.d.cts

@@ -0,0 +1,213 @@
+import { b as LiveGraphSnapshot, L as LiveGraph } from '../types-BzLD8bjb.cjs';
+import { J as Journal, a as LiveCard, R as ReactiveGraph } from '../journal-BJDjWb5Q.cjs';
+import { f as GraphEvent, T as TaskConfig } from '../types-CMFSIjpc.cjs';
+
+/**
+ * Board Live Cards — Disk persistence + CLI for ReactiveGraph.
+ *
+ * Library:
+ *   initBoard(dir)     — create dir + board-graph.json (idempotent)
+ *   loadBoard(dir)     — read board-graph.json → LiveGraph
+ *   saveBoard(dir, rg) — rg.snapshot() → write board-graph.json
+ *
+ * CLI:
+ *   board-live-cards init <dir>
+ *   board-live-cards status --rg <dir>
+ *   board-live-cards add-cards --rg <dir> --card <card.json>
+ *   board-live-cards run-sources-internal --card <card.json> --token <callbackToken> --rg <dir>
+ *
+ * Card transform:
+ *   liveCardToTaskConfig(card) — LiveCard → TaskConfig (handler mapping)
+ */
+
+/** Envelope stored in board-graph.json — wraps the LiveGraph snapshot with journal pointer. */
+interface BoardEnvelope {
+    lastDrainedJournalId: string;
+    graph: LiveGraphSnapshot;
+}
+interface JournalEntry {
+    id: string;
+    event: GraphEvent;
+}
+declare class BoardJournal implements Journal {
+    private readonly journalPath;
+    private lastDrainedId;
+    constructor(journalPath: string, lastDrainedJournalId: string);
+    append(event: GraphEvent): void;
+    drain(): GraphEvent[];
+    get size(): number;
+    get lastDrainedJournalId(): string;
+}
+interface CardInventoryEntry {
+    cardId: string;
+    cardFilePath: string;
+    addedAt: string;
+}
+declare function readCardInventory(boardDir: string): CardInventoryEntry[];
+declare function lookupCardPath(boardDir: string, cardId: string): string | null;
+declare function appendCardInventory(boardDir: string, entry: CardInventoryEntry): void;
+/**
+ * Initialize a board directory.
+ * - Dir doesn't exist → create it, write empty board-graph.json
+ * - Dir exists + valid board-graph.json → no-op, return 'exists'
+ * - Dir exists + non-empty (no valid board-graph.json) → throw
+ */
+declare function initBoard(dir: string): 'created' | 'exists';
+declare function loadBoardEnvelope(dir: string): BoardEnvelope;
+declare function loadBoard(dir: string): LiveGraph;
+declare function saveBoard(dir: string, rg: ReactiveGraph, journal: BoardJournal): void;
+/**
+ * Acquire an exclusive lock on the board, run `fn`, then release.
+ * Uses proper-lockfile on board-graph.json.
+ */
+declare function withBoardLock<T>(boardDir: string, fn: () => T): T;
+interface SourceTokenPayload {
+    /** Original callback token from the reactive graph (encodes taskName) */
+    cbk: string;
+    /** Board directory (absolute path) */
+    rg: string;
+    /** Card id */
+    cid: string;
+    /** sources[].bindTo */
+    b: string;
+    /** sources[].outputFile (relative to boardDir) */
+    d: string;
+}
+declare function encodeSourceToken(payload: SourceTokenPayload): string;
+declare function decodeSourceToken(token: string): SourceTokenPayload | null;
+interface SourceRuntimeEntry {
+    lastRequestedAt?: string;
+    lastFetchedAt?: string;
+    lastError?: string;
+}
+interface CardRuntimeState {
+    _sources: Record<string, SourceRuntimeEntry>;
+}
+/**
+ * Append a raw event to the journal file. No lock, no file read.
+ * Safe for hundreds of concurrent callers (appendFileSync is atomic for small writes).
+ */
+declare function appendEventToJournal(boardDir: string, event: GraphEvent): void;
+/**
+ * Read journal entries after the given ID. Pure file read, no mutation.
+ */
+declare function getUndrainedEntries(boardDir: string, lastDrainedId: string): JournalEntry[];
+/**
+ * Run one lock-guarded processing pass for this board.
+ *
+ * GUARANTEE (single-pass only):
+ * - At most one process performs this pass at a time (board lock).
+ * - If lock is acquired, exactly one drain/apply/save cycle is executed.
+ * - If lock is busy, returns false immediately (no waiting).
+ *
+ * This function does NOT guarantee full settlement; it only advances the baton
+ * by one cycle in the relay model.
+ */
+declare function processAccumulatedEvents(boardDir: string): boolean;
+/**
+ * Schedule continued draining until the board eventually settles.
+ *
+ * GUARANTEE (system-level eventual progress):
+ * - Default behavior launches a detached background worker process that runs
+ *   `process-accumulated-events --inline-loop`.
+ * - Returns quickly to caller; does not synchronously wait for settlement.
+ * - Under relay assumptions, pending entries eventually drain to zero:
+ *   1) at least one runner continues, 2) no crash/forced exit in relay window,
+ *   3) lock remains healthy, 4) new events do not arrive forever.
+ *
+ * INTERNAL MODE:
+ * - `inlineLoop: true` executes the while(pending) loop in the current process.
+ * - Used by the worker command to avoid recursive worker spawning.
+ */
+declare function processAccumulatedEventsInfinitePass(boardDir: string, settleDelayMs?: number, options?: {
+    inlineLoop?: boolean;
+}): Promise<boolean>;
+/**
+ * Forced drain entrypoint: first run one immediate pass, then delegate to
+ * infinite-pass continuation.
+ *
+ * GUARANTEE:
+ * - In default mode, this guarantees immediate forward progress (single pass)
+ *   and guaranteed scheduling of eventual continuation (background worker).
+ * - In `inlineLoop` mode, this runs full in-process settle loop and returns
+ *   only after pending reaches zero (or lock contention aborts loop).
+ */
+declare function processAccumulatedEventsForced(boardDir: string, options?: {
+    inlineLoop?: boolean;
+}): Promise<void>;
+type BoardLiveCard = LiveCard;
+/**
+ * Transform a LiveCard into a TaskConfig for the reactive graph.
+ *
+ * Every card gets handler: 'card-handler'.
+ * The handler inspects the card and decides what to do:
+ * run compute, invoke sources.
+ */
+declare function liveCardToTaskConfig(card: BoardLiveCard): TaskConfig;
+/**
+ * Spin up a ReactiveGraph from a board directory with all handlers wired.
+ *
+ * Single handler:
+ *   card-handler — reads card.json, loads sourcesData from outputFiles, runs CardCompute,
+ *                  checks undelivered sources, emits task-completed or spawns run-sources-internal.
+ *                  Fire & forget — returns 'task-initiated' immediately.
+ */
+interface BoardReactiveGraph {
+    rg: ReactiveGraph;
+    journal: BoardJournal;
+}
+declare function createBoardReactiveGraph(boardDir: string): BoardReactiveGraph;
+interface BoardStatusCard {
+    name: string;
+    status: string;
+    error?: {
+        message: string;
+        code?: string;
+        at?: string;
+        source?: 'task-runtime' | 'source-fetch' | 'timeout' | 'unknown';
+    };
+    requires: string[];
+    requires_satisfied: string[];
+    requires_missing: string[];
+    provides_declared: string[];
+    provides_runtime: string[];
+    blocked_by: string[];
+    unblocks: string[];
+    runtime: {
+        attempt_count: number;
+        restart_count: number;
+        in_progress_since: string | null;
+        last_transition_at: string | null;
+        last_completed_at: string | null;
+        last_restarted_at: string | null;
+        status_age_ms: number | null;
+    };
+}
+interface BoardStatusObject {
+    schema_version: 'v1';
+    meta: {
+        board: {
+            path: string;
+        };
+    };
+    summary: {
+        card_count: number;
+        completed: number;
+        eligible: number;
+        pending: number;
+        blocked: number;
+        unresolved: number;
+        failed?: number;
+        in_progress?: number;
+        orphan_cards?: number;
+        topology?: {
+            edge_count: number;
+            max_fan_out_card: string | null;
+            max_fan_out: number;
+        };
+    };
+    cards: BoardStatusCard[];
+}
+declare function cli(argv: string[]): Promise<void>;
+
+export { type BoardEnvelope, BoardJournal, type BoardLiveCard, type BoardReactiveGraph, type BoardStatusCard, type BoardStatusObject, type CardInventoryEntry, type CardRuntimeState, type JournalEntry, type SourceRuntimeEntry, type SourceTokenPayload, appendCardInventory, appendEventToJournal, cli, createBoardReactiveGraph, decodeSourceToken, encodeSourceToken, getUndrainedEntries, initBoard, liveCardToTaskConfig, loadBoard, loadBoardEnvelope, lookupCardPath, processAccumulatedEvents, processAccumulatedEventsForced, processAccumulatedEventsInfinitePass, readCardInventory, saveBoard, withBoardLock };

package/dist/cli/board-live-cards-cli.d.ts

@@ -0,0 +1,213 @@
+import { b as LiveGraphSnapshot, L as LiveGraph } from '../types-C2eJ7DAV.js';
+import { J as Journal, a as LiveCard, R as ReactiveGraph } from '../journal-B_2JnBMF.js';
+import { f as GraphEvent, T as TaskConfig } from '../types-CMFSIjpc.js';
+
+/**
+ * Board Live Cards — Disk persistence + CLI for ReactiveGraph.
+ *
+ * Library:
+ *   initBoard(dir)     — create dir + board-graph.json (idempotent)
+ *   loadBoard(dir)     — read board-graph.json → LiveGraph
+ *   saveBoard(dir, rg) — rg.snapshot() → write board-graph.json
+ *
+ * CLI:
+ *   board-live-cards init <dir>
+ *   board-live-cards status --rg <dir>
+ *   board-live-cards add-cards --rg <dir> --card <card.json>
+ *   board-live-cards run-sources-internal --card <card.json> --token <callbackToken> --rg <dir>
+ *
+ * Card transform:
+ *   liveCardToTaskConfig(card) — LiveCard → TaskConfig (handler mapping)
+ */
+
+/** Envelope stored in board-graph.json — wraps the LiveGraph snapshot with journal pointer. */
+interface BoardEnvelope {
+    lastDrainedJournalId: string;
+    graph: LiveGraphSnapshot;
+}
+interface JournalEntry {
+    id: string;
+    event: GraphEvent;
+}
+declare class BoardJournal implements Journal {
+    private readonly journalPath;
+    private lastDrainedId;
+    constructor(journalPath: string, lastDrainedJournalId: string);
+    append(event: GraphEvent): void;
+    drain(): GraphEvent[];
+    get size(): number;
+    get lastDrainedJournalId(): string;
+}
+interface CardInventoryEntry {
+    cardId: string;
+    cardFilePath: string;
+    addedAt: string;
+}
+declare function readCardInventory(boardDir: string): CardInventoryEntry[];
+declare function lookupCardPath(boardDir: string, cardId: string): string | null;
+declare function appendCardInventory(boardDir: string, entry: CardInventoryEntry): void;
+/**
+ * Initialize a board directory.
+ * - Dir doesn't exist → create it, write empty board-graph.json
+ * - Dir exists + valid board-graph.json → no-op, return 'exists'
+ * - Dir exists + non-empty (no valid board-graph.json) → throw
+ */
+declare function initBoard(dir: string): 'created' | 'exists';
+declare function loadBoardEnvelope(dir: string): BoardEnvelope;
+declare function loadBoard(dir: string): LiveGraph;
+declare function saveBoard(dir: string, rg: ReactiveGraph, journal: BoardJournal): void;
+/**
+ * Acquire an exclusive lock on the board, run `fn`, then release.
+ * Uses proper-lockfile on board-graph.json.
+ */
+declare function withBoardLock<T>(boardDir: string, fn: () => T): T;
+interface SourceTokenPayload {
+    /** Original callback token from the reactive graph (encodes taskName) */
+    cbk: string;
+    /** Board directory (absolute path) */
+    rg: string;
+    /** Card id */
+    cid: string;
+    /** sources[].bindTo */
+    b: string;
+    /** sources[].outputFile (relative to boardDir) */
+    d: string;
+}
+declare function encodeSourceToken(payload: SourceTokenPayload): string;
+declare function decodeSourceToken(token: string): SourceTokenPayload | null;
+interface SourceRuntimeEntry {
+    lastRequestedAt?: string;
+    lastFetchedAt?: string;
+    lastError?: string;
+}
+interface CardRuntimeState {
+    _sources: Record<string, SourceRuntimeEntry>;
+}
+/**
+ * Append a raw event to the journal file. No lock, no file read.
+ * Safe for hundreds of concurrent callers (appendFileSync is atomic for small writes).
+ */
+declare function appendEventToJournal(boardDir: string, event: GraphEvent): void;
+/**
+ * Read journal entries after the given ID. Pure file read, no mutation.
+ */
+declare function getUndrainedEntries(boardDir: string, lastDrainedId: string): JournalEntry[];
+/**
+ * Run one lock-guarded processing pass for this board.
+ *
+ * GUARANTEE (single-pass only):
+ * - At most one process performs this pass at a time (board lock).
+ * - If lock is acquired, exactly one drain/apply/save cycle is executed.
+ * - If lock is busy, returns false immediately (no waiting).
+ *
+ * This function does NOT guarantee full settlement; it only advances the baton
+ * by one cycle in the relay model.
+ */
+declare function processAccumulatedEvents(boardDir: string): boolean;
+/**
+ * Schedule continued draining until the board eventually settles.
+ *
+ * GUARANTEE (system-level eventual progress):
+ * - Default behavior launches a detached background worker process that runs
+ *   `process-accumulated-events --inline-loop`.
+ * - Returns quickly to caller; does not synchronously wait for settlement.
+ * - Under relay assumptions, pending entries eventually drain to zero:
+ *   1) at least one runner continues, 2) no crash/forced exit in relay window,
+ *   3) lock remains healthy, 4) new events do not arrive forever.
+ *
+ * INTERNAL MODE:
+ * - `inlineLoop: true` executes the while(pending) loop in the current process.
+ * - Used by the worker command to avoid recursive worker spawning.
+ */
+declare function processAccumulatedEventsInfinitePass(boardDir: string, settleDelayMs?: number, options?: {
+    inlineLoop?: boolean;
+}): Promise<boolean>;
+/**
+ * Forced drain entrypoint: first run one immediate pass, then delegate to
+ * infinite-pass continuation.
+ *
+ * GUARANTEE:
+ * - In default mode, this guarantees immediate forward progress (single pass)
+ *   and guaranteed scheduling of eventual continuation (background worker).
+ * - In `inlineLoop` mode, this runs full in-process settle loop and returns
+ *   only after pending reaches zero (or lock contention aborts loop).
+ */
+declare function processAccumulatedEventsForced(boardDir: string, options?: {
+    inlineLoop?: boolean;
+}): Promise<void>;
+type BoardLiveCard = LiveCard;
+/**
+ * Transform a LiveCard into a TaskConfig for the reactive graph.
+ *
+ * Every card gets handler: 'card-handler'.
+ * The handler inspects the card and decides what to do:
+ * run compute, invoke sources.
+ */
+declare function liveCardToTaskConfig(card: BoardLiveCard): TaskConfig;
+/**
+ * Spin up a ReactiveGraph from a board directory with all handlers wired.
+ *
+ * Single handler:
+ *   card-handler — reads card.json, loads sourcesData from outputFiles, runs CardCompute,
+ *                  checks undelivered sources, emits task-completed or spawns run-sources-internal.
+ *                  Fire & forget — returns 'task-initiated' immediately.
+ */
+interface BoardReactiveGraph {
+    rg: ReactiveGraph;
+    journal: BoardJournal;
+}
+declare function createBoardReactiveGraph(boardDir: string): BoardReactiveGraph;
+interface BoardStatusCard {
+    name: string;
+    status: string;
+    error?: {
+        message: string;
+        code?: string;
+        at?: string;
+        source?: 'task-runtime' | 'source-fetch' | 'timeout' | 'unknown';
+    };
+    requires: string[];
+    requires_satisfied: string[];
+    requires_missing: string[];
+    provides_declared: string[];
+    provides_runtime: string[];
+    blocked_by: string[];
+    unblocks: string[];
+    runtime: {
+        attempt_count: number;
+        restart_count: number;
+        in_progress_since: string | null;
+        last_transition_at: string | null;
+        last_completed_at: string | null;
+        last_restarted_at: string | null;
+        status_age_ms: number | null;
+    };
+}
+interface BoardStatusObject {
+    schema_version: 'v1';
+    meta: {
+        board: {
+            path: string;
+        };
+    };
+    summary: {
+        card_count: number;
+        completed: number;
+        eligible: number;
+        pending: number;
+        blocked: number;
+        unresolved: number;
+        failed?: number;
+        in_progress?: number;
+        orphan_cards?: number;
+        topology?: {
+            edge_count: number;
+            max_fan_out_card: string | null;
+            max_fan_out: number;
+        };
+    };
+    cards: BoardStatusCard[];
+}
+declare function cli(argv: string[]): Promise<void>;
+
+export { type BoardEnvelope, BoardJournal, type BoardLiveCard, type BoardReactiveGraph, type BoardStatusCard, type BoardStatusObject, type CardInventoryEntry, type CardRuntimeState, type JournalEntry, type SourceRuntimeEntry, type SourceTokenPayload, appendCardInventory, appendEventToJournal, cli, createBoardReactiveGraph, decodeSourceToken, encodeSourceToken, getUndrainedEntries, initBoard, liveCardToTaskConfig, loadBoard, loadBoardEnvelope, lookupCardPath, processAccumulatedEvents, processAccumulatedEventsForced, processAccumulatedEventsInfinitePass, readCardInventory, saveBoard, withBoardLock };