yaml-flow 7.1.0 → 8.0.1

package/lib/board-live-cards-node.d.cts

@@ -0,0 +1,178 @@
+import { I as InvocationAdapter } from './types-DkFvgxwq.cjs';
+export { D as DescribeEnvelope } from './types-DkFvgxwq.cjs';
+import { a as KindValueRef } from './storage-interface-BhAON-gW.cjs';
+export { p as parseRef, s as serializeRef } from './storage-interface-BhAON-gW.cjs';
+import { e as BoardNonCorePlatformAdapter, d as BoardPlatformAdapter } from './board-live-cards-public-BnmRAbQV.cjs';
+export { f as BOARD_GRAPH_KEY, g as BoardLiveCardsNonCorePublic, c as BoardLiveCardsPublic, C as CommandInput, a as CommandResult, E as EMPTY_CONFIG, L as LiveCard, S as SNAPSHOT_SCHEMA_VERSION_V1, h as createBoardLiveCardsNonCorePublic, i as createBoardLiveCardsPublic, j as createCardStore } from './board-live-cards-public-BnmRAbQV.cjs';
+import { ExecutionRef, ArgsMassaging } from './execution-refs.cjs';
+export { executionRefFromScriptPath, parseExecutionRef, serializeExecutionRef } from './execution-refs.cjs';
+export { createCardStorePublic } from './card-store-public.cjs';
+export { c as createArtifactsStore, a as createArtifactsStorePublic, b as createCardFileMetadataStore, d as createChatArtifactsStore, e as createFileArtifactsStore } from './artifacts-store-lib-public-DGa8BpJT.cjs';
+import './types-BBhqYGhE.cjs';
+
+/**
+ * cli/common/args-massaging — JSONata-based mapping from logical args to
+ * transport-specific shape.
+ *
+ * `argsMassaging` is a property of `ExecutionRef`, so honoring it is the job
+ * of every adapter (Node spawn, HTTP, Azure Function, etc.). This helper is
+ * the shared pure-JSONata implementation reused by all adapters.
+ *
+ * Adapters call this as the first step inside their `invokeRefSync` /
+ * `dispatchExecution` implementation, then perform their transport using
+ * `cmdArgs` / `body` / `url`.
+ */
+
+interface MassagedArgs {
+    /** Resolved argv tail for local transports. */
+    cmdArgs?: string[];
+    /** Resolved stdin payload for local transports. */
+    stdin?: unknown;
+    /** Resolved final URL string for http transports. */
+    url?: string;
+    /** Resolved request headers for http transports. */
+    headers?: Record<string, string>;
+    /** Resolved request body for http transports. */
+    body?: unknown;
+}
+
+/**
+ * execution-adapter.ts
+ *
+ * Node.js-specific adapter that resolves an ExecutionRef + logical args
+ * into a physical invocation (process spawn, HTTP request, or built-in call).
+ *
+ * This is the platform layer that pairs with execution-interface.ts (pure types).
+ * Import this only from Node contexts — not from browser bundles.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * WELL-KNOWN INVOCATION KINDS
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  invokeTaskExecutor(ref, args)
+ *    Standard task-executor protocol.
+ *    Logical args: { subcommand, inRef, outRef, errRef?, extra? }
+ *    Default cmdTemplate (local): ['subcommand', '--in-ref', inRef, '--out-ref', outRef, '--err-ref', errRef]
+ *    Default body (http):         { subcommand, inRef, outRef, errRef }
+ *
+ *  invokeBoardCliCallback(ref, args)
+ *    Back-channel from a task-executor to the board CLI.
+ *    Logical args: { command, argv[] }
+ *    Resolves 'built-in' to the board CLI script alongside cliDir.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * BUILT-IN RESOLUTION
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  howToRun: 'built-in' with whatToRun: 'b64:<base64url({"kind":"built-in","value":"source-cli-task-executor"})>'
+ *  → resolves to node <cliDir>/source-cli-task-executor.js
+ *
+ *  howToRun: 'built-in' with whatToRun: 'b64:<base64url({"kind":"built-in","value":"board-live-cards"})>'
+ *  → resolves to node <cliDir>/board-live-cards-cli.js (via buildBoardCliInvocation)
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * argsMassaging EVALUATION
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  Each argsMassaging field is a JSONata expression evaluated against the
+ *  logical args object merged with { whatToRun } (the address from the ref).
+ *
+ *  If argsMassaging is absent, the adapter uses its default mapping.
+ */
+
+/** Normalized envelope returned by invokeRefSync. */
+interface InvokeRefResult {
+    /** Outcome key — drives transitions in the step machine ('success' | 'failure' | custom). */
+    result: string;
+    /** Response payload as a record (always object-shaped; raw stdout wrapped under `stdout` if not JSON object). */
+    data: Record<string, unknown>;
+    /** Optional human-readable error detail. */
+    error?: string;
+}
+interface InvokeRefSyncOptions {
+    /** Directory used to resolve `built-in` refs (defaults to ref's cwd / process cwd). */
+    cliDir?: string;
+    /** Working directory for the spawned child (default: process cwd). */
+    cwd?: string;
+    /** Timeout in milliseconds (default: 30_000). */
+    timeoutMs?: number;
+    /** Label used in error messages (default: 'invokeRefSync'). */
+    label?: string;
+}
+interface InvokeExecutionRefOptions extends InvokeRefSyncOptions {
+    /** Extra async transport handlers keyed by `ExecutionRef.howToRun`. */
+    transports?: Record<string, TransportInvoker>;
+    /** Extra synchronous transport handlers keyed by `ExecutionRef.howToRun`. */
+    syncTransports?: Record<string, SyncTransportInvoker>;
+}
+type TransportInvoker = (ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeExecutionRefOptions) => Promise<InvokeRefResult>;
+type SyncTransportInvoker = (ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeExecutionRefOptions) => InvokeRefResult;
+interface CreateExecutionRefInvokerOptions extends InvokeExecutionRefOptions {
+}
+interface ExecutionRefInvoker {
+    invoke(ref: ExecutionRef, args: Record<string, unknown>): Promise<InvokeRefResult>;
+    invokeSync(ref: ExecutionRef, args: Record<string, unknown>): InvokeRefResult;
+}
+declare function evaluateArgsMassaging(argsMassaging: ArgsMassaging | undefined, args: Record<string, unknown>, label?: string): MassagedArgs;
+declare function invokeExecutionRef(ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeExecutionRefOptions): Promise<InvokeRefResult>;
+declare function invokeExecutionRefSync(ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeExecutionRefOptions): InvokeRefResult;
+declare function createExecutionRefInvoker(options?: CreateExecutionRefInvokerOptions): ExecutionRefInvoker;
+/**
+ * Invoke an ExecutionRef synchronously with a request/reply contract.
+ *
+ * Used by:
+ *   - step-machine ref steps (each step's handler dispatches through here)
+ *   - any utility that needs sync request/reply against an ExecutionRef
+ *
+ * Behavior:
+ *   1. Resolve `ref.argsMassaging` against `args` to get cmdArgs / stdin / body.
+ *   2. Build the local base spec (node/python/process + script path).
+ *   3. Spawn synchronously with `JSON.stringify(stdin ?? args)` on stdin.
+ *   4. Map exit code into envelope:
+ *        exit 0 → { result: 'success', data: parsed-stdout-or-{stdout: raw} }
+ *        non-0  → { result: 'failure', data: { error: stderr-or-exit-detail } }
+ *
+ * The framework (engine) never inspects payload shape; it only routes on `result`.
+ */
+declare function invokeRefSync(ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeRefSyncOptions): InvokeRefResult;
+
+/**
+ * fs-board-adapter.ts
+ *
+ * Wires Node.js / FS platform adapters into BoardPlatformAdapter and
+ * BoardNonCorePlatformAdapter, and provides FS-specific board utility functions.
+ *
+ * Everything in the board-live-cards system that is platform-free lives in
+ * src/cli/common/. All FS / Node.js / process concerns live here.
+ *
+ * Re-exports the full public API so consumers only need to import from this file.
+ */
+
+/**
+ * Creates an InvocationAdapter backed by Node.js `spawn`/`spawnSync`.
+ *
+ * Supports howToRun: 'local-node'
+ *   → spawns the script as a detached Node.js child process (fire-and-forget).
+ *
+ * Pass to createSingleBoardServerRuntime / createMultiBoardServerRuntime as
+ * the `invocationAdapter` option. This is the reference Node.js implementation;
+ * replace with your own for Azure Functions, Lambda, etc.
+ */
+declare function createNodeSpawnInvocationAdapter(): InvocationAdapter;
+type FsBoardAdapterOpts = {
+    onWarn?: (msg: string) => void;
+    suppressSpawn?: boolean;
+    notifyChannel?: string;
+};
+type FsBoardNonCoreAdapterOpts = {
+    onWarn?: (msg: string) => void;
+};
+declare function createFsBoardPlatformAdapter(baseRef: KindValueRef, cliDirOrOpts?: string | FsBoardAdapterOpts, maybeOpts?: FsBoardAdapterOpts): BoardPlatformAdapter;
+declare function createFsBoardNonCorePlatformAdapter(baseRef: KindValueRef, cliDirOrOpts?: string | FsBoardNonCoreAdapterOpts, maybeOpts?: FsBoardNonCoreAdapterOpts): BoardNonCorePlatformAdapter;
+/**
+ * Extract the serialized board ref from a source token (which has a `br` field).
+ * Returns null for callback tokens (which don't carry a board ref).
+ */
+declare function decodeBoardRefFromToken(token: string): string | null;
+
+export { BoardNonCorePlatformAdapter, BoardPlatformAdapter, type CreateExecutionRefInvokerOptions, ExecutionRef, type ExecutionRefInvoker, InvocationAdapter, type InvokeExecutionRefOptions, type InvokeRefResult, KindValueRef, type SyncTransportInvoker, type TransportInvoker, createExecutionRefInvoker, createFsBoardNonCorePlatformAdapter, createFsBoardPlatformAdapter, createNodeSpawnInvocationAdapter, decodeBoardRefFromToken, evaluateArgsMassaging, invokeExecutionRef, invokeExecutionRefSync, invokeRefSync };

package/lib/board-live-cards-node.d.ts

@@ -0,0 +1,178 @@
+import { I as InvocationAdapter } from './types-CBxkYuLY.js';
+export { D as DescribeEnvelope } from './types-CBxkYuLY.js';
+import { a as KindValueRef } from './storage-interface-BhAON-gW.js';
+export { p as parseRef, s as serializeRef } from './storage-interface-BhAON-gW.js';
+import { e as BoardNonCorePlatformAdapter, d as BoardPlatformAdapter } from './board-live-cards-public-CsmYrvpd.js';
+export { f as BOARD_GRAPH_KEY, g as BoardLiveCardsNonCorePublic, c as BoardLiveCardsPublic, C as CommandInput, a as CommandResult, E as EMPTY_CONFIG, L as LiveCard, S as SNAPSHOT_SCHEMA_VERSION_V1, h as createBoardLiveCardsNonCorePublic, i as createBoardLiveCardsPublic, j as createCardStore } from './board-live-cards-public-CsmYrvpd.js';
+import { ExecutionRef, ArgsMassaging } from './execution-refs.js';
+export { executionRefFromScriptPath, parseExecutionRef, serializeExecutionRef } from './execution-refs.js';
+export { createCardStorePublic } from './card-store-public.js';
+export { c as createArtifactsStore, a as createArtifactsStorePublic, b as createCardFileMetadataStore, d as createChatArtifactsStore, e as createFileArtifactsStore } from './artifacts-store-lib-public-BABrgFkV.js';
+import './types-BBhqYGhE.js';
+
+/**
+ * cli/common/args-massaging — JSONata-based mapping from logical args to
+ * transport-specific shape.
+ *
+ * `argsMassaging` is a property of `ExecutionRef`, so honoring it is the job
+ * of every adapter (Node spawn, HTTP, Azure Function, etc.). This helper is
+ * the shared pure-JSONata implementation reused by all adapters.
+ *
+ * Adapters call this as the first step inside their `invokeRefSync` /
+ * `dispatchExecution` implementation, then perform their transport using
+ * `cmdArgs` / `body` / `url`.
+ */
+
+interface MassagedArgs {
+    /** Resolved argv tail for local transports. */
+    cmdArgs?: string[];
+    /** Resolved stdin payload for local transports. */
+    stdin?: unknown;
+    /** Resolved final URL string for http transports. */
+    url?: string;
+    /** Resolved request headers for http transports. */
+    headers?: Record<string, string>;
+    /** Resolved request body for http transports. */
+    body?: unknown;
+}
+
+/**
+ * execution-adapter.ts
+ *
+ * Node.js-specific adapter that resolves an ExecutionRef + logical args
+ * into a physical invocation (process spawn, HTTP request, or built-in call).
+ *
+ * This is the platform layer that pairs with execution-interface.ts (pure types).
+ * Import this only from Node contexts — not from browser bundles.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * WELL-KNOWN INVOCATION KINDS
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  invokeTaskExecutor(ref, args)
+ *    Standard task-executor protocol.
+ *    Logical args: { subcommand, inRef, outRef, errRef?, extra? }
+ *    Default cmdTemplate (local): ['subcommand', '--in-ref', inRef, '--out-ref', outRef, '--err-ref', errRef]
+ *    Default body (http):         { subcommand, inRef, outRef, errRef }
+ *
+ *  invokeBoardCliCallback(ref, args)
+ *    Back-channel from a task-executor to the board CLI.
+ *    Logical args: { command, argv[] }
+ *    Resolves 'built-in' to the board CLI script alongside cliDir.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * BUILT-IN RESOLUTION
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  howToRun: 'built-in' with whatToRun: 'b64:<base64url({"kind":"built-in","value":"source-cli-task-executor"})>'
+ *  → resolves to node <cliDir>/source-cli-task-executor.js
+ *
+ *  howToRun: 'built-in' with whatToRun: 'b64:<base64url({"kind":"built-in","value":"board-live-cards"})>'
+ *  → resolves to node <cliDir>/board-live-cards-cli.js (via buildBoardCliInvocation)
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * argsMassaging EVALUATION
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  Each argsMassaging field is a JSONata expression evaluated against the
+ *  logical args object merged with { whatToRun } (the address from the ref).
+ *
+ *  If argsMassaging is absent, the adapter uses its default mapping.
+ */
+
+/** Normalized envelope returned by invokeRefSync. */
+interface InvokeRefResult {
+    /** Outcome key — drives transitions in the step machine ('success' | 'failure' | custom). */
+    result: string;
+    /** Response payload as a record (always object-shaped; raw stdout wrapped under `stdout` if not JSON object). */
+    data: Record<string, unknown>;
+    /** Optional human-readable error detail. */
+    error?: string;
+}
+interface InvokeRefSyncOptions {
+    /** Directory used to resolve `built-in` refs (defaults to ref's cwd / process cwd). */
+    cliDir?: string;
+    /** Working directory for the spawned child (default: process cwd). */
+    cwd?: string;
+    /** Timeout in milliseconds (default: 30_000). */
+    timeoutMs?: number;
+    /** Label used in error messages (default: 'invokeRefSync'). */
+    label?: string;
+}
+interface InvokeExecutionRefOptions extends InvokeRefSyncOptions {
+    /** Extra async transport handlers keyed by `ExecutionRef.howToRun`. */
+    transports?: Record<string, TransportInvoker>;
+    /** Extra synchronous transport handlers keyed by `ExecutionRef.howToRun`. */
+    syncTransports?: Record<string, SyncTransportInvoker>;
+}
+type TransportInvoker = (ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeExecutionRefOptions) => Promise<InvokeRefResult>;
+type SyncTransportInvoker = (ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeExecutionRefOptions) => InvokeRefResult;
+interface CreateExecutionRefInvokerOptions extends InvokeExecutionRefOptions {
+}
+interface ExecutionRefInvoker {
+    invoke(ref: ExecutionRef, args: Record<string, unknown>): Promise<InvokeRefResult>;
+    invokeSync(ref: ExecutionRef, args: Record<string, unknown>): InvokeRefResult;
+}
+declare function evaluateArgsMassaging(argsMassaging: ArgsMassaging | undefined, args: Record<string, unknown>, label?: string): MassagedArgs;
+declare function invokeExecutionRef(ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeExecutionRefOptions): Promise<InvokeRefResult>;
+declare function invokeExecutionRefSync(ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeExecutionRefOptions): InvokeRefResult;
+declare function createExecutionRefInvoker(options?: CreateExecutionRefInvokerOptions): ExecutionRefInvoker;
+/**
+ * Invoke an ExecutionRef synchronously with a request/reply contract.
+ *
+ * Used by:
+ *   - step-machine ref steps (each step's handler dispatches through here)
+ *   - any utility that needs sync request/reply against an ExecutionRef
+ *
+ * Behavior:
+ *   1. Resolve `ref.argsMassaging` against `args` to get cmdArgs / stdin / body.
+ *   2. Build the local base spec (node/python/process + script path).
+ *   3. Spawn synchronously with `JSON.stringify(stdin ?? args)` on stdin.
+ *   4. Map exit code into envelope:
+ *        exit 0 → { result: 'success', data: parsed-stdout-or-{stdout: raw} }
+ *        non-0  → { result: 'failure', data: { error: stderr-or-exit-detail } }
+ *
+ * The framework (engine) never inspects payload shape; it only routes on `result`.
+ */
+declare function invokeRefSync(ref: ExecutionRef, args: Record<string, unknown>, options?: InvokeRefSyncOptions): InvokeRefResult;
+
+/**
+ * fs-board-adapter.ts
+ *
+ * Wires Node.js / FS platform adapters into BoardPlatformAdapter and
+ * BoardNonCorePlatformAdapter, and provides FS-specific board utility functions.
+ *
+ * Everything in the board-live-cards system that is platform-free lives in
+ * src/cli/common/. All FS / Node.js / process concerns live here.
+ *
+ * Re-exports the full public API so consumers only need to import from this file.
+ */
+
+/**
+ * Creates an InvocationAdapter backed by Node.js `spawn`/`spawnSync`.
+ *
+ * Supports howToRun: 'local-node'
+ *   → spawns the script as a detached Node.js child process (fire-and-forget).
+ *
+ * Pass to createSingleBoardServerRuntime / createMultiBoardServerRuntime as
+ * the `invocationAdapter` option. This is the reference Node.js implementation;
+ * replace with your own for Azure Functions, Lambda, etc.
+ */
+declare function createNodeSpawnInvocationAdapter(): InvocationAdapter;
+type FsBoardAdapterOpts = {
+    onWarn?: (msg: string) => void;
+    suppressSpawn?: boolean;
+    notifyChannel?: string;
+};
+type FsBoardNonCoreAdapterOpts = {
+    onWarn?: (msg: string) => void;
+};
+declare function createFsBoardPlatformAdapter(baseRef: KindValueRef, cliDirOrOpts?: string | FsBoardAdapterOpts, maybeOpts?: FsBoardAdapterOpts): BoardPlatformAdapter;
+declare function createFsBoardNonCorePlatformAdapter(baseRef: KindValueRef, cliDirOrOpts?: string | FsBoardNonCoreAdapterOpts, maybeOpts?: FsBoardNonCoreAdapterOpts): BoardNonCorePlatformAdapter;
+/**
+ * Extract the serialized board ref from a source token (which has a `br` field).
+ * Returns null for callback tokens (which don't carry a board ref).
+ */
+declare function decodeBoardRefFromToken(token: string): string | null;
+
+export { BoardNonCorePlatformAdapter, BoardPlatformAdapter, type CreateExecutionRefInvokerOptions, ExecutionRef, type ExecutionRefInvoker, InvocationAdapter, type InvokeExecutionRefOptions, type InvokeRefResult, KindValueRef, type SyncTransportInvoker, type TransportInvoker, createExecutionRefInvoker, createFsBoardNonCorePlatformAdapter, createFsBoardPlatformAdapter, createNodeSpawnInvocationAdapter, decodeBoardRefFromToken, evaluateArgsMassaging, invokeExecutionRef, invokeExecutionRefSync, invokeRefSync };