yaml-flow 8.5.3 → 8.6.1

package/cli/execution-interface-BCIhu1gO.d.ts

@@ -1,442 +0,0 @@
-/**
- * storage-interface.ts
- *
- * Three minimal storage primitives that together cover all persistence needs
- * of the board-live-cards system. Any backend (Node fs, CosmosDB, Azure Blob,
- * browser localStorage, in-memory test double) implements these three interfaces.
- *
- * The pure-logic stores in board-live-cards-all-stores.ts depend only on these
- * interfaces — never on Node built-ins.
- *
- *  Blob    — raw string content at a logical, backend-neutral key
- *  Journal — append-only log with cursor-based reads
- *  KV      — key-value store with list/delete
- *
- * Mapping to existing storage adapters:
- *
- *   CardStorageAdapter
- *     inventory (cardId → { blobRef, checksum, fileMetadata? })  → KV
- *     card JSON files                                             → Blob
- *     source output files                                         → Blob
- *
- *   JournalStorageAdapter     → Journal (board-journal.jsonl)
- *
- *   ExecutionRequestStore → KV (keyed by journalId, via createFsKvStorage)
- *
- *   StateSnapshotStorageAdapter
- *     board-graph.json (packed single JSON, written atomically)   → Blob
- *     per-card sidecars (cards/<id>/runtime, fetched-sources-manifest) → KV
- */
-interface BlobStat {
-    key: string;
-    size: number;
-    updatedAt?: string;
-    contentType?: string;
-}
-interface BlobStorage {
-    /** Returns raw content string, or null if the blob does not exist. */
-    read(key: string): string | null;
-    /** Write content at key. Implementations should be atomic (write-rename). */
-    write(key: string, content: string): void;
-    /** Returns true if a blob exists at key. */
-    exists(key: string): boolean;
-    /** Delete the blob at key. No-op if it does not exist. */
-    remove(key: string): void;
-    /** Optional binary read for file-like artifacts. */
-    readBytes?(key: string): Uint8Array | null;
-    /** Optional binary write for file-like artifacts. */
-    writeBytes?(key: string, content: Uint8Array): void;
-    /** List all keys that start with the given prefix. */
-    listKeys(prefix?: string): string[];
-    /** Optional metadata lookup. */
-    stat?(key: string): BlobStat | null;
-    /**
-     * Optional: resolve a key to a transport-neutral KindValueRef (e.g. for
-     * handing the underlying location to a spawned child process or remote worker).
-     *   FS: { kind: 'fs-path', value: <absolute path under rootDir> }
-     *   Other backends: backend-specific ref
-     */
-    keyRef?(key: string): KindValueRef;
-}
-interface KindValueRef {
-    readonly kind: string;
-    readonly value: string;
-}
-/** Serialize a KindValueRef to the wire format: b64:<base64url(json)> */
-declare function serializeRef(ref: KindValueRef): string;
-/** Parse a wire-format ref string (b64:<base64url(json)>) into a KindValueRef. */
-declare function parseRef(s: string): KindValueRef;
-interface JournalEntry {
-    id: string;
-    payload: unknown;
-}
-interface JournalReadResult {
-    entries: JournalEntry[];
-    /** The id of the last entry returned, suitable for use as the next cursor. */
-    newCursor: string | null;
-}
-interface JournalStorage {
-    /** Append an entry. The storage layer assigns the id. */
-    append(payload: unknown): JournalEntry;
-    /** Read ALL entries (for index rebuilds, full replay). */
-    readAll(): JournalEntry[];
-    /**
-     * Read entries appended after the given cursor id.
-     * If cursor is null/empty, returns all entries from the beginning.
-     */
-    readAfter(cursor: string | null): JournalReadResult;
-    /** Truncate all entries. Optional — not all backends support it. */
-    clear?(): void;
-}
-interface KVStorage {
-    /** Returns the stored value, or null if the key does not exist. */
-    read(key: string): unknown | null;
-    /** Write value at key. Overwrites any existing value. */
-    write(key: string, value: unknown): void;
-    /** Delete the key. No-op if it does not exist. */
-    delete(key: string): void;
-    /**
-     * List all keys, optionally filtered to those starting with prefix.
-     * Order is implementation-defined.
-     */
-    listKeys(prefix?: string): string[];
-}
-interface ScratchStorage extends BlobStorage {
-    /**
-     * Allocate a new unique key. Does NOT create any underlying object — caller
-     * must write to it (e.g. via a spawned child) before it has content.
-     * prefix and suffix are sanitized; both are optional.
-     */
-    getUniqueKey(prefix?: string, suffix?: string): string;
-    /**
-     * Allocate a new unique key AND write data at it atomically. Returns the
-     * new key. Counts as a write for sweep-trigger purposes.
-     */
-    create(data: string, prefix?: string, suffix?: string): string;
-    /** Resolve a key to a transport-neutral ref (e.g. for child-process handoff). */
-    keyRef(key: string): KindValueRef;
-    /** Backend-agnostic config bag (used for retention policy and similar knobs). */
-    config: {
-        get(k: string): unknown;
-        set(k: string, v: unknown): void;
-    };
-}
-interface ArchiveFactory {
-    /** Open (or create) a named append-only stream rooted inside the archive. */
-    stream(name: string): JournalStorage;
-    /** Open (or create) a named blob namespace rooted inside the archive. */
-    blob(name: string): BlobStorage;
-    /** List all stream names present in the archive. */
-    listStreams(prefix?: string): string[];
-    /** List all blob namespace names present in the archive. */
-    listBlobs(prefix?: string): string[];
-    /** Backend-agnostic config bag (retention knobs and similar). */
-    config: {
-        get(k: string): unknown;
-        set(k: string, v: unknown): void;
-    };
-}
-interface AtomicRelayLock {
-    /**
-     * Attempt to acquire the lock without blocking.
-     * Returns a `release` function if successful, or `null` if the lock is
-     * already held by another actor (relay: that actor will complete the work).
-     */
-    tryAcquire(): (() => void) | null;
-}
-
-/**
- * execution-interface.ts
- *
- * Pure module — no Node/platform imports.  Safe for any runtime.
- *
- * Defines the portable descriptor types for invoking any executable target,
- * regardless of transport (local process, HTTP endpoint, cloud function, etc.).
- *
- * Parallel to storage-interface.ts (which describes WHERE data lives), this
- * module describes HOW to invoke a piece of logic.
- *
- * ────────────────────────────────────────────────────────────────────────────
- * CORE CONCEPTS
- * ────────────────────────────────────────────────────────────────────────────
- *
- *  ExecutionRef — self-contained, serializable JSON descriptor for one invocation target.
- *    • howToRun    — transport / runtime kind (discriminator)
- *    • whatToRun   — address of the artifact (KindValueRef wire form: b64:<base64url(json)>)
- *    • argsMassaging — optional JSONata expressions that map logical args → physical call shape
- *    • meta        — optional human-readable label (e.g. 'task-executor', 'chat-handler')
- *
- *  ExecutionResult — standardized envelope returned by any invocation.
- *    • status: 'success' | 'fail' | 'error'
- *    • data   — KindValueRef wire form pointing to output blob (on success)
- *    • error  — human-readable message (on fail/error)
- *
- * ────────────────────────────────────────────────────────────────────────────
- * howToRun VALUES
- * ────────────────────────────────────────────────────────────────────────────
- *
- *  'local-node'      node <whatToRun> [argv...]
- *  'local-python'    python <whatToRun> [argv...]
- *  'local-process'   execute <whatToRun> directly (shebang / pre-resolved binary)
- *  'http:post'       HTTP POST to <whatToRun>
- *  'http:get'        HTTP GET to <whatToRun>
- *  'built-in'        resolved by the adapter to a well-known internal implementation
- *
- * ────────────────────────────────────────────────────────────────────────────
- * argsMassaging
- * ────────────────────────────────────────────────────────────────────────────
- *
- *  Each field is a JSONata expression evaluated against the caller's logical args object.
- *  If argsMassaging is omitted, the adapter uses its default mapping for the howToRun kind.
- *
- *  Local transports (local-node, local-python, local-process):
- *    cmdTemplate   — array of JSONata exprs, each producing one argv string
- *    stdinTemplate — JSONata expr producing the stdin payload object
- *
- *  HTTP transports (http:post, http:get, azure-function, firebase, etc.):
- *    urlTemplate    — JSONata expr producing the final URL string
- *    headerTemplate — JSONata expr producing the request headers object
- *    bodyTemplate   — JSONata expr producing the request body object
- *
- * ────────────────────────────────────────────────────────────────────────────
- * SERIALIZATION
- * ────────────────────────────────────────────────────────────────────────────
- *
- *  ExecutionRef is a plain JSON object — store it as-is on disk, in Cosmos, or any DB.
- *  No special encoding needed.  parseExecutionRef / serializeExecutionRef are thin
- *  JSON wrappers provided for symmetry with storage-interface.
- *
- * ────────────────────────────────────────────────────────────────────────────
- * USAGE EXAMPLES
- * ────────────────────────────────────────────────────────────────────────────
- *
- *  // Built-in source-cli task executor (resolved by adapter from cliDir):
- *  const builtIn: ExecutionRef = {
- *    meta: 'task-executor',
- *    howToRun: 'built-in',
- *    whatToRun: 'b64:<base64url({"kind":"built-in","value":"source-cli-task-executor"})>',
- *  };
- *
- *  // External local-node task executor with default protocol args:
- *  const local: ExecutionRef = {
- *    meta: 'task-executor',
- *    howToRun: 'local-node',
- *    whatToRun: 'b64:<base64url({"kind":"fs-path","value":"/path/to/my-executor.js"})>',
- *  };
- *
- *  // Packaged yaml-flow CLI entrypoint resolved by the Node adapter:
- *  const yamlFlowCli: ExecutionRef = {
- *    meta: 'chat-handler',
- *    howToRun: 'local-node',
- *    whatToRun: 'b64:<base64url({"kind":"yaml-flow-cli","value":"chat-store-cli.js"})>',
- *  };
- *
- *  // Azure Function task executor with custom arg mapping:
- *  const azureFn: ExecutionRef = {
- *    meta: 'task-executor',
- *    howToRun: 'http:post',
- *    whatToRun: 'b64:<base64url({"kind":"http-url","value":"https://myfn.azurewebsites.net/api/task-executor"})>',
- *    argsMassaging: {
- *      urlTemplate: "whatToRun & '?op=' & subcommand",
- *      headerTemplate: "{ 'Authorization': 'Bearer ' & token }",
- *      bodyTemplate: "{ 'inRef': inRef, 'outRef': outRef }",
- *    },
- *  };
- *
- *  // Chat handler over HTTP with a different logical args shape:
- *  const chatHandler: ExecutionRef = {
- *    meta: 'chat-handler',
- *    howToRun: 'http:post',
- *    whatToRun: 'b64:<base64url({"kind":"http-url","value":"https://myfn.azurewebsites.net/api/chat"})>',
- *    argsMassaging: {
- *      bodyTemplate: "{ 'message': message, 'context': context, 'sessionId': sessionId }",
- *    },
- *  };
- */
-/**
- * Optional JSONata-based transforms applied to the raw invoke result.
- * Context for all expressions: `{ output: { result, data, error? } }`.
- * All fields are optional.
- */
-interface OutputTransforms {
-    /**
-     * JSONata expression that produces the transition name string.
-     * @example "output.code = 200 ? 'success' : 'failure'"
-     */
-    resultExpr?: string;
-    /**
-     * JSONata expression that produces the data object.
-     * @example "{ 'value': output.body.value }"
-     */
-    dataTemplate?: string;
-    /**
-     * JSONata expression that produces the error string, or $undefined() to clear it.
-     * @example "output.code != 200 ? output.error_message : $undefined()"
-     */
-    errorExpr?: string;
-}
-/**
- * Optional JSONata-based mapping from logical args → physical invocation shape.
- *
- * Each field is a JSONata expression string evaluated against the caller's
- * logical args object (e.g. `{ inRef, outRef, errRef }` for a task-executor).
- *
- * If argsMassaging is omitted entirely, the execution adapter uses its default
- * mapping for the given howToRun kind.
- */
-interface ArgsMassaging {
-    /**
-     * Array of JSONata expressions — each evaluates to one argv string.
-     * The resolved strings are appended after the base command.
-     *
-     * @example
-     * cmdTemplate: [
-     *   "'run-source-fetch'",
-     *   "'--in-ref'",  "inRef",
-     *   "'--out-ref'", "outRef",
-     *   "'--err-ref'", "errRef",
-     * ]
-     */
-    cmdTemplate?: string[];
-    /**
-     * JSONata expression that produces the stdin payload object.
-     * Evaluated against the logical args.
-     * If omitted, `JSON.stringify(args)` is sent on stdin.
-     *
-     * @example
-     * stdinTemplate: "{ 'X': x, 'multiplier': 2 }"
-     */
-    stdinTemplate?: string;
-    /**
-     * JSONata expression that produces the final URL string.
-     * The input context includes 'whatToRun' (the base URL from the ref)
-     * plus all logical args.
-     *
-     * @example
-     * urlTemplate: "whatToRun & '?op=' & subcommand"
-     */
-    urlTemplate?: string;
-    /**
-     * JSONata expression that produces the request headers object.
-     * Merged on top of the default headers (`Content-Type: application/json`).
-     *
-     * @example
-     * headerTemplate: "{ 'Authorization': 'Bearer ' & token }"
-     */
-    headerTemplate?: string;
-    /**
-     * JSONata expression that produces the request body object.
-     * Evaluated against the logical args object.
-     *
-     * @example
-     * bodyTemplate: "{ 'inRef': inRef, 'outRef': outRef }"
-     */
-    bodyTemplate?: string;
-}
-type KnownExecutionTransport = 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in' | 'in-browser';
-type ExecutionTransportKind = KnownExecutionTransport | (string & {});
-/**
- * Self-contained, serializable descriptor for invoking a target.
- *
- * Stores everything needed to make the physical call — transport kind,
- * artifact address, and optional arg-mapping expressions.
- * Serialize as plain JSON; no special wire encoding required.
- */
-interface ExecutionRef {
-    /**
-     * Optional human-readable label identifying the role of this invocation.
-     * Not used for dispatch — purely for logging and diagnostics.
-     * @example 'task-executor', 'chat-handler', 'board-live-cards'
-     */
-    meta?: string;
-    /**
-     * Transport and runtime kind — determines how whatToRun is invoked.
-     * @see module JSDoc for the full list of supported values.
-     */
-    howToRun: ExecutionTransportKind;
-    /**
-      * Address of the artifact to run. Two valid forms:
-      *   - string:  must be KindValueRef wire form `b64:<base64url(json)>` (programmatically generated via serializeRef)
-      *   - object:  `{ kind: string; value: string }` plain object (human-authored flow files — normalized by the handler factory)
-      * Prefer `kind: 'yaml-flow-cli'` when targeting a packaged public yaml-flow CLI entrypoint.
-      * Use `kind: 'fs-path'` for external scripts or non-packaged local executables.
-      * @example 'b64:<base64url({"kind":"yaml-flow-cli","value":"chat-store-cli.js"})>'
-      * @example { kind: 'http-url', value: '/api/workiq/ask' }
-      * @example { kind: 'fs-path', value: './my-handler.js' }
-     */
-    whatToRun: string | {
-        kind: string;
-        value: string;
-    };
-    /**
-     * Optional JSONata-based mapping from logical args → physical call shape.
-     * When omitted, the adapter applies its default protocol for the howToRun kind.
-     */
-    argsMassaging?: ArgsMassaging;
-    /**
-     * Optional JSONata-based transforms applied to the raw invoke result
-     * before it reaches the step-machine engine.
-     *
-     * Context for all expressions: `{ output: { result, data, error? } }`
-     * where `output` is the raw { result, data, error? } returned by invokeRefSync.
-     *
-     * All fields are optional — only defined ones override the raw value.
-     *
-     * @example
-     * outputTransforms:
-     *   resultExpr:   "output.code = 200 ? 'success' : 'failure'"
-     *   dataTemplate: "{ 'value': output.body.value }"
-     *   errorExpr:    "output.code != 200 ? output.error_message : $undefined()"
-     */
-    outputTransforms?: OutputTransforms;
-    /**
-     * Opaque executor-specific configuration.
-     * For local transports, base64-encoded and passed as --extra <base64-json> in the argv.
-     * For HTTP transports, available in argsMassaging templates as the `extra` binding.
-     * Stored with the ref so it travels as a single unit with the invocation descriptor.
-     */
-    extra?: Record<string, unknown>;
-}
-/**
- * Standardized result envelope returned by any execution.
- *
- * Replaces the implicit "file-exists = success, absent = failure" protocol
- * with an explicit status field.  The data ref points to the output blob.
- */
-interface ExecutionResult {
-    /** Outcome of the execution. */
-    status: 'success' | 'fail' | 'error';
-    /**
-     * KindValueRef wire form pointing to the output blob.
-     * Present only when status === 'success'.
-     */
-    data?: string;
-    /**
-     * Human-readable error or failure message.
-     * Present when status === 'fail' or 'error'.
-     */
-    error?: string;
-}
-/**
- * Create an ExecutionRef from a script path string (e.g. from a --task-executor CLI arg).
- * File extension determines howToRun:
- *   .js / .mjs → 'local-node'
- *   .py        → 'local-python'
- *   other      → 'local-process'
- *
- * @param scriptPath  Absolute or relative path to the script / binary.
- * @param extra       Optional opaque executor config stored on the ref.
- */
-declare function executionRefFromScriptPath(scriptPath: string, extra?: Record<string, unknown>): ExecutionRef;
-/**
- * Serialize an ExecutionRef to a JSON string for storage.
- * Plain JSON.stringify — no special encoding.
- */
-declare function serializeExecutionRef(ref: ExecutionRef): string;
-/**
- * Parse a JSON string back into an ExecutionRef.
- * Throws if the string is not valid JSON or is missing required fields.
- */
-declare function parseExecutionRef(s: string): ExecutionRef;
-
-export { type ArgsMassaging as A, type BlobStorage as B, type ExecutionRef as E, type JournalStorage as J, type KindValueRef as K, type ScratchStorage as S, type ExecutionResult as a, type KVStorage as b, type ArchiveFactory as c, type AtomicRelayLock as d, executionRefFromScriptPath as e, parseRef as f, serializeRef as g, parseExecutionRef as p, serializeExecutionRef as s };