@farmslot/recipe-harness 0.1.0 → 0.2.0

package/dist/core/predicates.js

@@ -0,0 +1,102 @@
+import { isDeepStrictEqual } from 'node:util';
+import { isRecord } from './json.js';
+export function evaluateNodeGate(node, outputs) {
+    const root = Object.fromEntries(outputs);
+    if (node.when != null && !evaluatePredicate(root, node.when)) {
+        return { run: false, reason: 'when predicate was false' };
+    }
+    if (node.unless != null && evaluatePredicate(root, node.unless)) {
+        return { run: false, reason: 'unless predicate was true' };
+    }
+    return { run: true };
+}
+export function evaluatePredicate(root, predicate) {
+    if (!isRecord(predicate))
+        throw new Error('Predicate must be an assertion object.');
+    if (Array.isArray(predicate.all))
+        return predicate.all.every((entry) => evaluatePredicate(root, entry));
+    if (Array.isArray(predicate.any))
+        return predicate.any.some((entry) => evaluatePredicate(root, entry));
+    if (Array.isArray(predicate.none))
+        return !predicate.none.some((entry) => evaluatePredicate(root, entry));
+    const pathValue = typeof predicate.path === 'string' ? predicate.path : '$';
+    const actual = pathValue === '$' ? root : getPathValue(root, pathValue.replace(/^\$\./, ''));
+    const operator = typeof predicate.operator === 'string' ? predicate.operator : 'truthy';
+    const expected = predicate.value;
+    switch (operator) {
+        case 'exists':
+            return actual !== undefined;
+        case 'not_null':
+            return actual != null;
+        case 'truthy':
+            return Boolean(actual);
+        case 'falsy':
+            return !actual;
+        case 'eq':
+            return actual === expected;
+        case 'ne':
+        case 'neq':
+            return actual !== expected;
+        case 'deep_eq':
+            return isDeepStrictEqual(actual, expected);
+        case 'contains':
+            return containsValue(actual, expected);
+        case 'not_contains':
+            return !containsValue(actual, expected);
+        case 'matches':
+            return typeof expected === 'string' && new RegExp(expected).test(String(actual ?? ''));
+        case 'one_of':
+            return Array.isArray(expected) && expected.some((entry) => isDeepStrictEqual(entry, actual));
+        case 'gt':
+        case 'gte':
+        case 'lt':
+        case 'lte':
+            return compareNumbers(actual, expected, operator);
+        case 'length_eq':
+        case 'length_gt':
+        case 'length_gte':
+        case 'length_lt':
+        case 'length_lte':
+            return compareNumbers(lengthOf(actual), expected, operator.replace('length_', ''));
+        default:
+            throw new Error(`Unsupported predicate operator ${operator}.`);
+    }
+}
+export function getPathValue(root, dottedPath) {
+    return dottedPath
+        .split('.')
+        .filter(Boolean)
+        .reduce((current, segment) => {
+        if (!isRecord(current) && !Array.isArray(current))
+            return undefined;
+        if (Array.isArray(current))
+            return current[Number(segment)];
+        return current[segment];
+    }, root);
+}
+function containsValue(actual, expected) {
+    if (typeof actual === 'string')
+        return actual.includes(String(expected));
+    if (Array.isArray(actual))
+        return actual.some((entry) => isDeepStrictEqual(entry, expected));
+    return false;
+}
+function lengthOf(actual) {
+    if (typeof actual === 'string' || Array.isArray(actual))
+        return actual.length;
+    if (isRecord(actual))
+        return Object.keys(actual).length;
+    return Number.NaN;
+}
+function compareNumbers(actual, expected, operator) {
+    if (typeof actual !== 'number' || typeof expected !== 'number')
+        return false;
+    if (operator === 'gt')
+        return actual > expected;
+    if (operator === 'gte')
+        return actual >= expected;
+    if (operator === 'lt')
+        return actual < expected;
+    return actual <= expected;
+}
+//# sourceMappingURL=predicates.js.map

package/dist/core/predicates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicates.js","sourceRoot":"","sources":["../../src/core/predicates.ts"],"names":[],"mappings":"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"}

package/dist/core/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/core/runner.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,aAAa,EACb,yBAAyB,EAIzB,YAAY,EAKb,MAAM,YAAY,CAAC;AAapB,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAGzE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,YAAY,CA8CnF"}

package/dist/core/runner.js

@@ -0,0 +1,532 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { getRecipeActionManifestActionNames, validateRecipeArtifactPackage, } from '@farmslot/protocol';
+import { JsonArtifactWriter, JsonSummaryWriter, JsonTraceWriter } from '../node/writers.js';
+import { collectFlows, executeInlineFlowCall } from './flows.js';
+import { extractWorkflowGraph, normalizePreconditionResult, resolveNextNode, } from './graph.js';
+import { buildHudNode } from './hud.js';
+import { isRecord, normalizeRelativePath, readJsonFile } from './json.js';
+import { evaluateNodeGate } from './predicates.js';
+import { recordSyntheticFailure, traceNodeMetadata } from './trace.js';
+import { assertManifestIsValid, assertRecipeMatchesManifest } from './validation.js';
+const HARNESS_VERSION = '0.1.0';
+const RUNNER_BUILT_IN_ACTIONS = new Set(['call']);
+const DEFAULT_MAX_FLOW_CALL_DEPTH = 8;
+const noopLogger = {
+    info() { },
+    warn() { },
+    error() { },
+};
+export function defineActionAdapter(adapter) {
+    if (!adapter.action.trim())
+        throw new Error('Action adapter action must be a non-empty string.');
+    return adapter;
+}
+export function createRecipeRunner(options) {
+    assertManifestIsValid(options.actionManifest);
+    const declaredActions = new Set(getRecipeActionManifestActionNames(options.actionManifest));
+    const adapterMap = new Map();
+    const preconditionMap = new Map();
+    const declaredPreconditions = new Set((options.actionManifest.pre_conditions ?? []).map((entry) => entry.id));
+    for (const checker of options.preconditions ?? []) {
+        if (!checker.id.trim())
+            throw new Error('Precondition checker id must be a non-empty string.');
+        if (!declaredPreconditions.has(checker.id)) {
+            throw new Error(`Precondition checker ${checker.id} is not declared by the action manifest.`);
+        }
+        if (preconditionMap.has(checker.id)) {
+            throw new Error(`Precondition checker ${checker.id} is registered more than once.`);
+        }
+        preconditionMap.set(checker.id, checker);
+    }
+    for (const adapter of options.adapters) {
+        if (!adapter.action.trim())
+            throw new Error('Action adapter action must be a non-empty string.');
+        if (!declaredActions.has(adapter.action) && adapter.testOnly !== true) {
+            throw new Error(`Adapter ${adapter.action} is not declared by the recipe action manifest.`);
+        }
+        if (adapterMap.has(adapter.action)) {
+            throw new Error(`Adapter ${adapter.action} is registered more than once.`);
+        }
+        adapterMap.set(adapter.action, adapter);
+    }
+    for (const action of declaredActions) {
+        if (!adapterMap.has(action) && !RUNNER_BUILT_IN_ACTIONS.has(action)) {
+            throw new Error(`Manifest action ${action} has no registered adapter.`);
+        }
+    }
+    return new DefaultRecipeRunner(options.actionManifest, adapterMap, preconditionMap, options.logger ?? noopLogger, options.hud, options.runner);
+}
+class DefaultRecipeRunner {
+    #actionManifest;
+    #adapters;
+    #preconditions;
+    #logger;
+    #hud;
+    #runnerProvenance;
+    constructor(actionManifest, adapters, preconditions, logger, hud, runnerProvenance) {
+        this.#actionManifest = actionManifest;
+        this.#adapters = adapters;
+        this.#preconditions = preconditions;
+        this.#logger = logger;
+        this.#hud = hud;
+        this.#runnerProvenance = runnerProvenance;
+    }
+    async run(request) {
+        if (!request.recipePath && request.recipeDocument == null) {
+            throw new Error('Recipe run requires recipePath or recipeDocument.');
+        }
+        const projectRoot = path.resolve(request.projectRoot ?? process.cwd());
+        const artifactsDir = path.resolve(request.artifactsDir);
+        const startedAt = new Date();
+        await mkdir(artifactsDir, { recursive: true });
+        const sourceRecipePath = request.recipePath ? path.resolve(request.recipePath) : undefined;
+        const recipe = request.recipeDocument ?? (await readJsonFile(sourceRecipePath));
+        assertRecipeMatchesManifest(recipe, this.#actionManifest);
+        const graph = extractWorkflowGraph(recipe);
+        const flowCatalog = await collectFlows(recipe, {
+            projectRoot,
+            recipeDir: sourceRecipePath ? path.dirname(sourceRecipePath) : projectRoot,
+        });
+        const artifactWriter = new JsonArtifactWriter(artifactsDir);
+        const traceWriter = new JsonTraceWriter(artifactsDir, this.#runnerProvenance);
+        const summaryWriter = new JsonSummaryWriter(artifactsDir);
+        const outputs = new Map();
+        const recipePath = await artifactWriter.copyRecipe(recipe);
+        let status = 'unknown';
+        let currentNodeId = graph.entry;
+        let mainStatus = 'unknown';
+        let runningTeardown = false;
+        const visited = new Set();
+        let transitionCount = 0;
+        const maxTransitions = Object.keys(graph.nodes).length * 3;
+        const preconditionStatus = await this.#runPreconditions({
+            graph,
+            recipe,
+            projectRoot,
+            artifactsDir,
+            request,
+            outputs,
+            artifactWriter,
+            traceWriter,
+        });
+        if (preconditionStatus === 'fail') {
+            status = 'fail';
+            currentNodeId = undefined;
+        }
+        while (currentNodeId) {
+            const activeNodeId = currentNodeId;
+            transitionCount += 1;
+            if (transitionCount > maxTransitions) {
+                const error = new Error('Recipe graph exceeded its maximum transition count.');
+                recordSyntheticFailure(traceWriter, activeNodeId, error);
+                status = 'fail';
+                break;
+            }
+            visited.add(activeNodeId);
+            const node = graph.nodes[activeNodeId];
+            if (!node) {
+                const error = new Error(`Recipe node ${activeNodeId} does not exist.`);
+                recordSyntheticFailure(traceWriter, activeNodeId, error);
+                status = 'fail';
+                break;
+            }
+            const action = String(node.action);
+            const adapter = action === 'call' ? undefined : this.#adapters.get(action);
+            if (action !== 'call' && !adapter) {
+                const error = new Error(`No adapter registered for action ${action}.`);
+                recordSyntheticFailure(traceWriter, activeNodeId, error, action);
+                status = 'fail';
+                break;
+            }
+            const nodeStartedAt = new Date();
+            const context = {
+                nodeId: activeNodeId,
+                recipe,
+                projectRoot,
+                artifactsDir,
+                env: request.env ?? {},
+                outputs,
+                getOutput(nodeId) {
+                    if (!outputs.has(nodeId))
+                        throw new Error(`No output recorded for node ${nodeId}.`);
+                    return outputs.get(nodeId);
+                },
+                resolveProjectPath(relativePath) {
+                    return path.join(projectRoot, normalizeRelativePath(relativePath));
+                },
+                resolveArtifactPath(relativePath) {
+                    return path.join(artifactsDir, normalizeRelativePath(relativePath));
+                },
+                registerArtifact(entry) {
+                    artifactWriter.register(entry);
+                },
+                logger: this.#logger,
+            };
+            try {
+                const gate = evaluateNodeGate(node, context.outputs);
+                if (!gate.run) {
+                    const next = resolveNextNode(node, {});
+                    traceWriter.record({
+                        nodeId: activeNodeId,
+                        action,
+                        ...traceNodeMetadata(node),
+                        startedAt: nodeStartedAt.toISOString(),
+                        endedAt: new Date().toISOString(),
+                        durationMs: Date.now() - nodeStartedAt.getTime(),
+                        ok: true,
+                        next,
+                        output: { skipped: true, reason: gate.reason },
+                    });
+                    currentNodeId = next;
+                    continue;
+                }
+                const hudStarted = await this.#publishHudProgressOrRecord(traceWriter, 'running', {
+                    nodeId: activeNodeId,
+                    action,
+                    node,
+                    recipe,
+                    index: transitionCount,
+                    total: Object.keys(graph.nodes).length,
+                    context,
+                });
+                if (!hudStarted) {
+                    status = 'fail';
+                    break;
+                }
+                const result = action === 'call'
+                    ? await executeInlineFlowCall({
+                        callNodeId: activeNodeId,
+                        node,
+                        context,
+                        flowCatalog,
+                        adapters: this.#adapters,
+                        traceWriter,
+                        callStack: [],
+                        maxCallDepth: DEFAULT_MAX_FLOW_CALL_DEPTH,
+                    })
+                    : await adapter.execute(node, context);
+                if (result.output !== undefined)
+                    outputs.set(activeNodeId, result.output);
+                for (const artifact of result.artifacts ?? [])
+                    artifactWriter.register(artifact);
+                const next = resolveNextNode(node, result);
+                traceWriter.record({
+                    nodeId: activeNodeId,
+                    action,
+                    ...traceNodeMetadata(node, result),
+                    startedAt: nodeStartedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - nodeStartedAt.getTime(),
+                    ok: true,
+                    next,
+                    status: result.status,
+                    output: result.output,
+                });
+                const hudCompleted = await this.#publishHudProgressOrRecord(traceWriter, result.status === 'fail' ? 'fail' : 'pass', {
+                    nodeId: activeNodeId,
+                    action,
+                    node,
+                    recipe,
+                    index: transitionCount,
+                    total: Object.keys(graph.nodes).length,
+                    context,
+                });
+                if (!hudCompleted) {
+                    status = 'fail';
+                    break;
+                }
+                if (result.status) {
+                    if (runningTeardown) {
+                        status = mainStatus === 'fail' ? 'fail' : result.status;
+                        break;
+                    }
+                    mainStatus = result.status;
+                    if (graph.teardownEntry) {
+                        runningTeardown = true;
+                        currentNodeId = graph.teardownEntry;
+                        continue;
+                    }
+                    status = result.status;
+                    break;
+                }
+                currentNodeId = next;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                traceWriter.record({
+                    nodeId: activeNodeId,
+                    action,
+                    ...traceNodeMetadata(node),
+                    startedAt: nodeStartedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - nodeStartedAt.getTime(),
+                    ok: false,
+                    error: message,
+                });
+                this.#logger.error(message);
+                await this.#publishHudProgressOrRecord(traceWriter, 'fail', {
+                    nodeId: activeNodeId,
+                    action,
+                    node,
+                    recipe,
+                    index: transitionCount,
+                    total: Object.keys(graph.nodes).length,
+                    context,
+                    error: message,
+                });
+                status = 'fail';
+                if (!runningTeardown && graph.teardownEntry) {
+                    mainStatus = 'fail';
+                    runningTeardown = true;
+                    currentNodeId = graph.teardownEntry;
+                    continue;
+                }
+                break;
+            }
+        }
+        artifactWriter.register({
+            path: 'summary.json',
+            type: 'summary',
+            label: 'Run summary',
+            category: 'system',
+        });
+        artifactWriter.register({
+            path: 'trace.json',
+            type: 'trace',
+            label: 'Execution trace',
+            category: 'system',
+        });
+        if (status === 'pass') {
+            const runHudStartedAt = new Date();
+            try {
+                await this.#publishRunHud(status, {
+                    recipe,
+                    projectRoot,
+                    artifactsDir,
+                    env: request.env ?? {},
+                    outputs,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                traceWriter.record({
+                    nodeId: 'recipe-complete:hud',
+                    action: 'app.hud',
+                    startedAt: runHudStartedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - runHudStartedAt.getTime(),
+                    ok: false,
+                    error: message,
+                });
+                this.#logger.error(`app.hud complete update failed: ${message}`);
+                status = 'fail';
+            }
+        }
+        const endedAt = new Date();
+        const tracePath = await traceWriter.write();
+        const trace = traceWriter.list();
+        const summary = {
+            status,
+            total: trace.length,
+            passed: trace.filter((entry) => entry.ok).length,
+            failed: trace.filter((entry) => !entry.ok).length,
+            startedAt: startedAt.toISOString(),
+            endedAt: endedAt.toISOString(),
+            durationMs: endedAt.getTime() - startedAt.getTime(),
+            harness: {
+                name: '@farmslot/recipe-harness',
+                version: HARNESS_VERSION,
+                runner_protocol_version: this.#actionManifest.runner_protocol_version,
+                action_registry_version: this.#actionManifest.action_registry_version,
+            },
+            ...(this.#runnerProvenance ? { runner: this.#runnerProvenance } : {}),
+        };
+        const summaryPath = await summaryWriter.write(summary);
+        const artifactManifestPath = await artifactWriter.write(status, this.#runnerProvenance);
+        const packageValidation = validateRecipeArtifactPackage({
+            recipe,
+            manifest: {
+                version: 1,
+                runStatus: status,
+                ...(this.#runnerProvenance ? { provenance: { runner: this.#runnerProvenance } } : {}),
+                artifacts: artifactWriter.list(),
+            },
+            artifactPaths: [
+                'recipe.json',
+                'summary.json',
+                'trace.json',
+                'artifact-manifest.json',
+                ...artifactWriter.list().map((entry) => entry.path),
+            ],
+        });
+        if (packageValidation.status === 'invalid') {
+            throw new Error(`Generated artifact package is invalid: ${packageValidation.findings
+                .map((finding) => `${finding.code} ${finding.path}`)
+                .join(', ')}`);
+        }
+        return { status, summaryPath, tracePath, artifactManifestPath, recipePath };
+    }
+    async #runPreconditions({ graph, recipe, projectRoot, artifactsDir, request, outputs, artifactWriter, traceWriter, }) {
+        for (const gate of graph.preconditions) {
+            const nodeId = `pre_conditions:${gate.id}`;
+            const checker = this.#preconditions.get(gate.id);
+            if (!checker) {
+                recordSyntheticFailure(traceWriter, nodeId, new Error(`Precondition ${gate.id} is declared by the recipe but has no checker registered.`), 'pre_condition');
+                return 'fail';
+            }
+            const startedAt = new Date();
+            const context = this.#createExecutionContext({
+                nodeId,
+                recipe,
+                projectRoot,
+                artifactsDir,
+                env: request.env ?? {},
+                outputs,
+                artifactWriter,
+            });
+            try {
+                const rawResult = await checker.execute(gate, context);
+                const result = normalizePreconditionResult(rawResult);
+                if (result.output !== undefined)
+                    outputs.set(nodeId, result.output);
+                if (result.ok === false) {
+                    throw new Error(result.error ?? `Precondition ${gate.id} failed.`);
+                }
+                traceWriter.record({
+                    nodeId,
+                    action: 'pre_condition',
+                    startedAt: startedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAt.getTime(),
+                    ok: true,
+                    output: result.output,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                traceWriter.record({
+                    nodeId,
+                    action: 'pre_condition',
+                    startedAt: startedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAt.getTime(),
+                    ok: false,
+                    error: message,
+                });
+                return 'fail';
+            }
+        }
+        return 'pass';
+    }
+    #createExecutionContext({ nodeId, recipe, projectRoot, artifactsDir, env, outputs, artifactWriter, }) {
+        return {
+            nodeId,
+            recipe,
+            projectRoot,
+            artifactsDir,
+            env,
+            outputs,
+            getOutput(nodeId) {
+                if (!outputs.has(nodeId))
+                    throw new Error(`No output recorded for node ${nodeId}.`);
+                return outputs.get(nodeId);
+            },
+            resolveProjectPath(relativePath) {
+                return path.join(projectRoot, normalizeRelativePath(relativePath));
+            },
+            resolveArtifactPath(relativePath) {
+                return path.join(artifactsDir, normalizeRelativePath(relativePath));
+            },
+            registerArtifact(entry) {
+                artifactWriter.register(entry);
+            },
+            logger: this.#logger,
+        };
+    }
+    #hudAction() {
+        if (this.#hud === false || this.#hud?.enabled === false)
+            return undefined;
+        return this.#adapters.has('app.hud') ? 'app.hud' : undefined;
+    }
+    async #publishHudProgressOrRecord(traceWriter, status, event) {
+        const startedAt = new Date();
+        try {
+            await this.#publishHudProgress(status, event);
+            return true;
+        }
+        catch (error) {
+            // HUD is first-class when advertised, so rendering failures fail the run.
+            // They are still recorded instead of aborting artifact package writing.
+            const message = error instanceof Error ? error.message : String(error);
+            traceWriter.record({
+                nodeId: `${event.nodeId}:hud:${status}`,
+                action: 'app.hud',
+                startedAt: startedAt.toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: Date.now() - startedAt.getTime(),
+                ok: false,
+                error: message,
+            });
+            this.#logger.error(`app.hud ${status} update failed for ${event.nodeId}: ${message}`);
+            return false;
+        }
+    }
+    async #publishHudProgress(status, event) {
+        const hudAction = this.#hudAction();
+        if (!hudAction || event.action === hudAction)
+            return;
+        const adapter = this.#adapters.get(hudAction);
+        if (!adapter)
+            return;
+        await adapter.execute(buildHudNode(status, event, this.#hud), event.context);
+    }
+    async #publishRunHud(status, request) {
+        const hudAction = this.#hudAction();
+        if (!hudAction)
+            return;
+        const adapter = this.#adapters.get(hudAction);
+        if (!adapter)
+            return;
+        const context = {
+            nodeId: 'recipe-complete',
+            recipe: request.recipe,
+            projectRoot: request.projectRoot,
+            artifactsDir: request.artifactsDir,
+            env: request.env,
+            outputs: request.outputs,
+            getOutput(nodeId) {
+                if (!request.outputs.has(nodeId))
+                    throw new Error(`No output recorded for node ${nodeId}.`);
+                return request.outputs.get(nodeId);
+            },
+            resolveProjectPath(relativePath) {
+                return path.join(request.projectRoot, normalizeRelativePath(relativePath));
+            },
+            resolveArtifactPath(relativePath) {
+                return path.join(request.artifactsDir, normalizeRelativePath(relativePath));
+            },
+            registerArtifact() { },
+            logger: this.#logger,
+        };
+        await adapter.execute({
+            action: hudAction,
+            title: this.#hudTitle(request.recipe),
+            status,
+            node_id: 'recipe-complete',
+            phase: 'complete',
+            flow: 'run',
+            detail: status === 'pass' ? 'Recipe completed' : 'Recipe failed',
+            text: status === 'pass' ? 'Recipe completed' : 'Recipe failed',
+            progress: { complete: true },
+        }, context);
+    }
+    #hudTitle(recipe) {
+        if (this.#hud && this.#hud.title)
+            return this.#hud.title;
+        if (isRecord(recipe) && typeof recipe.title === 'string')
+            return recipe.title;
+        return 'Recipe run';
+    }
+}
+//# sourceMappingURL=runner.js.map