adfinem 0.0.0 → 0.1.1

package/dist/engine/step-result.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { explainKnownError } from "./known-errors.js";
+export function hashInput(value) {
+    return createHash("sha256").update(JSON.stringify(value ?? {})).digest("hex");
+}
+export function durationBetween(startedAt, endedAt) {
+    const startedMs = Date.parse(startedAt);
+    const endedMs = Date.parse(endedAt);
+    if (!Number.isFinite(startedMs) || !Number.isFinite(endedMs))
+        return undefined;
+    return Math.max(0, endedMs - startedMs);
+}
+export function failedStep(stepId, layer, startedAt, input, error, evidence = []) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const explained = explainKnownError(err);
+    const endedAt = new Date().toISOString();
+    return {
+        stepId,
+        layer,
+        status: "failed",
+        startedAt,
+        endedAt,
+        durationMs: durationBetween(startedAt, endedAt),
+        inputHash: hashInput(input),
+        captures: {},
+        evidence,
+        error: {
+            message: explained.message,
+            stack: err.stack,
+            rawOutput: explained.hints.length > 0 ? `Hints:\n${explained.hints.map((hint) => `- ${hint}`).join("\n")}` : undefined
+        }
+    };
+}
+export function cancelledStep(stepId, layer, startedAt, input, evidence = []) {
+    const endedAt = new Date().toISOString();
+    return {
+        stepId,
+        layer,
+        status: "cancelled",
+        startedAt,
+        endedAt,
+        durationMs: durationBetween(startedAt, endedAt),
+        inputHash: hashInput(input),
+        captures: {},
+        evidence,
+        error: {
+            message: "Run was stopped by user request."
+        }
+    };
+}
+export function isCancellationError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+export function cancellationError() {
+    const error = new Error("Run was stopped by user request.");
+    error.name = "AbortError";
+    return error;
+}

package/dist/flows/catalog-normalizer.js

@@ -0,0 +1,72 @@
+import { normalizeBindParamRecord } from "../adapters/db/query-catalog.js";
+import { batchInputFileParamNames } from "../adapters/unix/batch-input-files.js";
+export function normalizeFlowCatalogParams(flow, catalogs) {
+    return {
+        ...flow,
+        nodes: flow.nodes.map((node) => normalizeNode(node, flow, catalogs))
+    };
+}
+function normalizeNode(node, flow, catalogs) {
+    if (node.type === "api_operation") {
+        return {
+            ...node,
+            postActions: node.postActions?.map((action) => normalizeAction(action, flow, catalogs))
+        };
+    }
+    if (node.type === "parallel") {
+        return {
+            ...node,
+            branches: node.branches.map((branch) => ({
+                ...branch,
+                nodes: branch.nodes.map((child) => normalizeNode(child, flow, catalogs))
+            }))
+        };
+    }
+    if (node.type === "loop") {
+        return {
+            ...node,
+            nodes: node.nodes.map((child) => normalizeNode(child, flow, catalogs))
+        };
+    }
+    return normalizeAction(node, flow, catalogs);
+}
+function normalizeAction(node, flow, catalogs) {
+    if (node.type === "db_query" || node.type === "db_assert" || node.type === "db_execute") {
+        const specs = catalogs.queries[node.query]?.params;
+        if (!specs || Object.keys(specs).length === 0)
+            return node;
+        return {
+            ...node,
+            params: normalizeNamedParams(normalizeBindParamRecord(node.params ?? node.input ?? {}), normalizeBindParamRecord(specs))
+        };
+    }
+    if (node.type === "unix_batch") {
+        const batch = catalogs.batches[node.batch];
+        const args = batch?.args ?? [];
+        const fileParamNames = batchInputFileParamNames(batch);
+        if (args.length === 0 && fileParamNames.length === 0)
+            return node;
+        return {
+            ...node,
+            params: normalizeNamedArgs(node.params ?? node.input ?? {}, args, fileParamNames)
+        };
+    }
+    return node;
+}
+function normalizeNamedParams(current, specs) {
+    const normalized = {};
+    for (const [name, spec] of Object.entries(specs)) {
+        if (current[name] !== undefined) {
+            normalized[name] = current[name];
+            continue;
+        }
+        if (spec.required) {
+            normalized[name] = "";
+        }
+    }
+    return normalized;
+}
+function normalizeNamedArgs(current, args, extraNames = []) {
+    const allowed = new Set([...args.map((arg) => arg.name), ...extraNames]);
+    return Object.fromEntries(Object.entries(current).filter(([name]) => allowed.has(name)));
+}

package/dist/flows/compiler.js

@@ -0,0 +1,237 @@
+export function compileFlow(flow, options = {}) {
+    const environment = options.environment ?? flow.environment;
+    const effectiveFlow = applyFlowEnvironmentInputs(flow, environment);
+    const steps = [];
+    const stepMap = [];
+    for (const node of orderedNodes(effectiveFlow)) {
+        if (node.disabled)
+            continue;
+        const step = compileNode(node);
+        steps.push(step);
+        stepMap.push({ flowNodeId: node.id, scenarioStepId: step.id, type: node.type });
+        if (node.type === "api_operation") {
+            for (const postAction of node.postActions ?? []) {
+                if (postAction.disabled)
+                    continue;
+                const postStep = compileNode(postAction, node);
+                steps.push(postStep);
+                stepMap.push({
+                    flowNodeId: postAction.id,
+                    scenarioStepId: postStep.id,
+                    type: postAction.type,
+                    postActionOf: node.id
+                });
+            }
+        }
+        appendControlStepMap(node, stepMap);
+    }
+    const scenario = {
+        id: effectiveFlow.id,
+        environment,
+        variables: effectiveFlow.variables,
+        steps
+    };
+    return { flow: effectiveFlow, scenario, stepMap };
+}
+export function applyFlowEnvironmentInputs(flow, environment = flow.environment) {
+    const inputSet = flow.environmentInputs?.[environment];
+    if (!inputSet)
+        return flow;
+    const nodeInputs = inputSet.nodes ?? {};
+    return {
+        ...flow,
+        variables: mergeRecords(flow.variables, inputSet.variables),
+        nodes: flow.nodes.map((node) => applyNodeEnvironmentInputs(node, nodeInputs))
+    };
+}
+export function orderedNodes(flow) {
+    if (!flow.edges?.length)
+        return flow.nodes;
+    if (flow.ui?.manualEdges)
+        return flow.nodes;
+    return linearOrderFromEdges(flow) ?? flow.nodes;
+}
+export function isCompleteLinearEdgeChain(flow) {
+    if (!flow.edges?.length)
+        return true;
+    if (flow.ui?.manualEdges)
+        return false;
+    return Boolean(linearOrderFromEdges(flow));
+}
+function linearOrderFromEdges(flow) {
+    if (!flow.edges?.length)
+        return flow.nodes;
+    if (flow.nodes.length <= 1)
+        return flow.nodes;
+    if (flow.edges.length !== flow.nodes.length - 1)
+        return undefined;
+    const byId = new Map(flow.nodes.map((node) => [node.id, node]));
+    const outgoing = new Map();
+    const incoming = new Set();
+    for (const edge of flow.edges) {
+        if (!byId.has(edge.from) || !byId.has(edge.to) || edge.from === edge.to)
+            return undefined;
+        if (outgoing.has(edge.from) || incoming.has(edge.to))
+            return undefined;
+        outgoing.set(edge.from, edge.to);
+        incoming.add(edge.to);
+    }
+    const starts = flow.nodes.filter((node) => !incoming.has(node.id));
+    if (starts.length !== 1)
+        return undefined;
+    const ordered = [];
+    const seen = new Set();
+    let current = starts[0];
+    while (current && !seen.has(current.id)) {
+        ordered.push(current);
+        seen.add(current.id);
+        const nextId = outgoing.get(current.id);
+        current = nextId ? byId.get(nextId) : undefined;
+    }
+    return seen.size === flow.nodes.length ? ordered : undefined;
+}
+function compileNode(node, postActionOf) {
+    if (node.type === "api_operation") {
+        return cleanStep({
+            id: node.id,
+            action: node.operation,
+            via: "api",
+            input: node.input ?? node.params,
+            request: node.request,
+            assertions: node.assertions,
+            capture: node.capture,
+            continueOnFailure: node.continueOnFailure,
+            expectedOutcome: node.expectedOutcome,
+            captureOnFailure: node.captureOnFailure
+        });
+    }
+    if (node.type === "db_query" || node.type === "db_assert" || node.type === "db_execute") {
+        return cleanStep({
+            id: node.id,
+            action: node.type,
+            via: "db",
+            query: node.query,
+            params: node.params ?? node.input,
+            assertions: node.assertions,
+            capture: node.capture,
+            continueOnFailure: node.continueOnFailure,
+            expectedOutcome: node.expectedOutcome,
+            captureOnFailure: node.captureOnFailure
+        });
+    }
+    if (node.type === "unix_batch") {
+        return cleanStep({
+            id: node.id,
+            action: "unix_batch",
+            via: "unix",
+            batch: node.batch,
+            params: node.params ?? node.input,
+            retry: node.retry,
+            assertions: node.assertions,
+            capture: node.capture,
+            continueOnFailure: node.continueOnFailure,
+            expectedOutcome: node.expectedOutcome,
+            captureOnFailure: node.captureOnFailure
+        });
+    }
+    if (node.type === "parallel") {
+        return cleanStep({
+            id: node.id,
+            action: "__parallel",
+            via: "control",
+            control: "parallel",
+            join: node.join ?? "all",
+            continueOnFailure: node.continueOnFailure,
+            branches: node.branches.map((branch) => ({
+                id: branch.id,
+                label: branch.label,
+                steps: branch.nodes.filter((child) => !child.disabled).map((child) => compileNode(child))
+            }))
+        });
+    }
+    if (node.type === "loop") {
+        return cleanStep({
+            id: node.id,
+            action: "__loop",
+            via: "control",
+            control: "loop",
+            loop: node.loop,
+            continueOnFailure: node.continueOnFailure,
+            steps: node.nodes.filter((child) => !child.disabled).map((child) => compileNode(child))
+        });
+    }
+    const unsupported = node;
+    throw new Error(`Unsupported flow node type '${unsupported.type ?? "unknown"}'${postActionOf ? ` after '${postActionOf.id}'` : ""}.`);
+}
+function applyNodeEnvironmentInputs(node, nodeInputs) {
+    if (node.type === "api_operation") {
+        const overrides = nodeInputs[node.id];
+        return {
+            ...node,
+            input: mergeRecords(node.input ?? node.params, overrides),
+            postActions: node.postActions?.map((action) => applyActionEnvironmentInputs(action, nodeInputs))
+        };
+    }
+    if (node.type === "parallel") {
+        return {
+            ...node,
+            branches: node.branches.map((branch) => ({
+                ...branch,
+                nodes: branch.nodes.map((child) => applyNodeEnvironmentInputs(child, nodeInputs))
+            }))
+        };
+    }
+    if (node.type === "loop") {
+        return {
+            ...node,
+            nodes: node.nodes.map((child) => applyNodeEnvironmentInputs(child, nodeInputs))
+        };
+    }
+    return applyActionEnvironmentInputs(node, nodeInputs);
+}
+function applyActionEnvironmentInputs(node, nodeInputs) {
+    const overrides = nodeInputs[node.id];
+    if (!overrides)
+        return node;
+    return {
+        ...node,
+        params: mergeRecords(node.params ?? node.input, overrides)
+    };
+}
+function mergeRecords(base, overrides) {
+    if (!base && !overrides)
+        return undefined;
+    return {
+        ...(base ?? {}),
+        ...(overrides ?? {})
+    };
+}
+function cleanStep(step) {
+    return Object.fromEntries(Object.entries(step).filter(([, value]) => value !== undefined));
+}
+export function flowNodeOutputPrefix(id) {
+    return `${id}.`;
+}
+export function nodeTypeLabel(type) {
+    return type.replace(/_/g, " ");
+}
+function appendControlStepMap(node, stepMap) {
+    if (node.type === "parallel") {
+        for (const branch of node.branches) {
+            for (const child of branch.nodes) {
+                if (child.disabled)
+                    continue;
+                stepMap.push({ flowNodeId: child.id, scenarioStepId: child.id, type: child.type });
+                appendControlStepMap(child, stepMap);
+            }
+        }
+    }
+    if (node.type === "loop") {
+        for (const child of node.nodes) {
+            if (child.disabled)
+                continue;
+            stepMap.push({ flowNodeId: child.id, scenarioStepId: child.id, type: child.type });
+            appendControlStepMap(child, stepMap);
+        }
+    }
+}

package/dist/flows/concat.js

@@ -0,0 +1,130 @@
+import { orderedNodes } from "./compiler.js";
+export function concatFlows(flows, options) {
+    if (flows.length < 2)
+        throw new Error("At least two flows are required to concatenate.");
+    const environment = options.environment ?? commonEnvironment(flows);
+    const variables = mergeVariables(flows, Boolean(options.allowVariableOverrides));
+    const usedIds = new Set();
+    const nodes = [];
+    for (const flow of flows) {
+        const sourceNodes = orderedNodes(flow);
+        const sourceIds = collectNodeIds(sourceNodes);
+        const needsPrefix = prefixRequired(options.nodePrefixMode ?? "auto", sourceIds, usedIds);
+        const prefix = `${sanitizeId(flow.id)}_`;
+        const idMap = new Map();
+        for (const id of sourceIds) {
+            const mapped = needsPrefix ? uniqueId(`${prefix}${id}`, usedIds) : uniqueId(id, usedIds);
+            idMap.set(id, mapped);
+            usedIds.add(mapped);
+        }
+        for (const node of sourceNodes) {
+            nodes.push(rewriteNode(node, idMap));
+        }
+    }
+    return {
+        version: 1,
+        id: options.id,
+        name: options.name,
+        environment,
+        variables,
+        nodes,
+        edges: buildTimelineEdges(nodes)
+    };
+}
+function commonEnvironment(flows) {
+    const environments = [...new Set(flows.map((flow) => flow.environment))];
+    if (environments.length === 1)
+        return environments[0];
+    throw new Error(`Input flows use different environments (${environments.join(", ")}). Pass --env to choose the generated flow environment.`);
+}
+function mergeVariables(flows, allowOverrides) {
+    const merged = {};
+    const sources = new Map();
+    for (const flow of flows) {
+        for (const [name, value] of Object.entries(flow.variables ?? {})) {
+            if (Object.prototype.hasOwnProperty.call(merged, name) && stableJson(merged[name]) !== stableJson(value) && !allowOverrides) {
+                throw new Error(`Variable '${name}' has different values in '${sources.get(name)}' and '${flow.id}'. Pass --allow-variable-overrides to keep the later value.`);
+            }
+            merged[name] = value;
+            sources.set(name, flow.id);
+        }
+    }
+    return Object.keys(merged).length ? merged : undefined;
+}
+function prefixRequired(mode, sourceIds, usedIds) {
+    if (mode === "always")
+        return true;
+    if (mode === "never")
+        return false;
+    for (const id of sourceIds) {
+        if (usedIds.has(id))
+            return true;
+    }
+    return false;
+}
+function collectNodeIds(nodes) {
+    const ids = new Set();
+    for (const node of nodes) {
+        ids.add(node.id);
+        if (node.type === "api_operation") {
+            for (const postAction of node.postActions ?? [])
+                ids.add(postAction.id);
+        }
+    }
+    return ids;
+}
+function rewriteNode(node, idMap) {
+    const rewritten = rewriteValue(node, idMap);
+    rewritten.id = idMap.get(node.id) ?? node.id;
+    if (rewritten.type === "api_operation") {
+        rewritten.postActions = rewritten.postActions?.map((action) => ({
+            ...action,
+            id: idMap.get(action.id) ?? action.id
+        }));
+    }
+    return rewritten;
+}
+function rewriteValue(value, idMap) {
+    if (typeof value === "string")
+        return rewriteReferences(value, idMap);
+    if (Array.isArray(value))
+        return value.map((entry) => rewriteValue(entry, idMap));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, rewriteValue(entry, idMap)]));
+    }
+    return value;
+}
+function rewriteReferences(value, idMap) {
+    return value.replace(/\$\{([A-Za-z0-9_-]+)\.([A-Za-z0-9_.-]+)\}/g, (match, nodeId, outputName) => {
+        const mapped = idMap.get(nodeId);
+        return mapped ? `\${${mapped}.${outputName}}` : match;
+    });
+}
+function buildTimelineEdges(nodes) {
+    if (nodes.length < 2)
+        return undefined;
+    return nodes.slice(0, -1).map((node, index) => ({ from: node.id, to: nodes[index + 1].id }));
+}
+function uniqueId(seed, usedIds) {
+    let candidate = sanitizeId(seed);
+    let suffix = 2;
+    while (usedIds.has(candidate)) {
+        candidate = `${sanitizeId(seed)}_${suffix}`;
+        suffix += 1;
+    }
+    return candidate;
+}
+function sanitizeId(value) {
+    const normalized = value.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
+    return normalized || "flow";
+}
+function stableJson(value) {
+    if (!value || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    return `{${Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+        .join(",")}}`;
+}

package/dist/flows/parser.js

@@ -0,0 +1,21 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import YAML from "yaml";
+import { flowFileSchema } from "./schema.js";
+const yamlOptions = { defaultStringType: "PLAIN", defaultKeyType: "PLAIN", lineWidth: 0 };
+export async function loadFlow(path) {
+    const parsed = YAML.parse(await readFile(path, "utf8"));
+    return flowFileSchema.parse(parsed);
+}
+export async function readFlowSource(path) {
+    return readFile(path, "utf8");
+}
+export async function writeFlow(path, flow) {
+    const outputPath = resolve(path);
+    await mkdir(dirname(outputPath), { recursive: true });
+    const validated = flowFileSchema.parse(flow);
+    await writeFile(outputPath, YAML.stringify(validated, yamlOptions), "utf8");
+}
+export function flowToYaml(flow) {
+    return YAML.stringify(flowFileSchema.parse(flow), yamlOptions);
+}

package/dist/flows/schema.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+import { apiAssertionSchema, apiRequestSpecSchema } from "../dsl/schema.js";
+const scalar = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const jsonValue = z.lazy(() => z.union([
+    scalar,
+    z.array(jsonValue),
+    z.record(jsonValue)
+]));
+const id = z.string().min(1).regex(/^[A-Za-z0-9_-]+$/);
+const mappingObject = z.record(jsonValue);
+const captureObject = z.record(z.string().min(1));
+const environmentInputSetSchema = z.object({
+    variables: mappingObject.optional(),
+    nodes: z.record(mappingObject).optional()
+}).strict();
+const retrySchema = z.object({
+    attempts: z.number().int().positive().optional(),
+    delaySeconds: z.number().nonnegative().optional()
+}).strict();
+const expectedOutcomeSchema = z.enum(["positive", "negative", "setup", "teardown"]);
+const loopDateFormatSchema = z.enum(["YYYY-MM-DD", "DD/MM/YYYY", "MM/DD/YYYY"]);
+const loopDateCursorSchema = z.object({
+    outputName: z.string().min(1).optional(),
+    start: z.string().min(1).optional(),
+    inputFormat: loopDateFormatSchema.optional(),
+    outputFormat: loopDateFormatSchema.optional(),
+    advance: z.object({
+        mode: z.enum(["days", "months", "nth_day_of_month", "first_of_month", "end_of_month"]),
+        amount: z.number().int().positive().optional(),
+        day: z.number().int().min(1).max(31).optional()
+    }).strict().optional()
+}).strict();
+const loopSpecSchema = z.object({
+    mode: z.enum(["count", "foreach"]),
+    count: z.union([z.number().int().nonnegative(), z.string()]).optional(),
+    items: jsonValue.optional(),
+    itemName: z.string().min(1).optional(),
+    maxIterations: z.number().int().positive().optional(),
+    dateCursor: loopDateCursorSchema.optional()
+}).strict();
+const parallelJoinModeSchema = z.enum(["all", "any", "fail_fast"]);
+const actionBase = {
+    id,
+    label: z.string().min(1).optional(),
+    input: mappingObject.optional(),
+    params: mappingObject.optional(),
+    request: apiRequestSpecSchema.optional(),
+    assertions: z.array(apiAssertionSchema).optional(),
+    capture: captureObject.optional(),
+    continueOnFailure: z.boolean().optional(),
+    expectedOutcome: expectedOutcomeSchema.optional(),
+    captureOnFailure: z.boolean().optional(),
+    disabled: z.boolean().optional(),
+    section: z.string().min(1).optional()
+};
+export const flowDbQueryNodeSchema = z.object({
+    ...actionBase,
+    type: z.literal("db_query"),
+    query: z.string().min(1)
+}).strict();
+export const flowDbAssertNodeSchema = z.object({
+    ...actionBase,
+    type: z.literal("db_assert"),
+    query: z.string().min(1)
+}).strict();
+export const flowDbExecuteNodeSchema = z.object({
+    ...actionBase,
+    type: z.literal("db_execute"),
+    query: z.string().min(1)
+}).strict();
+export const flowUnixBatchNodeSchema = z.object({
+    ...actionBase,
+    type: z.literal("unix_batch"),
+    batch: z.string().min(1),
+    retry: retrySchema.optional()
+}).strict();
+export const flowActionNodeSchema = z.discriminatedUnion("type", [
+    flowDbQueryNodeSchema,
+    flowDbAssertNodeSchema,
+    flowDbExecuteNodeSchema,
+    flowUnixBatchNodeSchema
+]);
+export const flowApiOperationNodeSchema = z.object({
+    id,
+    label: z.string().min(1).optional(),
+    type: z.literal("api_operation"),
+    operation: z.string().min(1),
+    input: mappingObject.optional(),
+    params: mappingObject.optional(),
+    request: apiRequestSpecSchema.optional(),
+    assertions: z.array(apiAssertionSchema).optional(),
+    capture: captureObject.optional(),
+    continueOnFailure: z.boolean().optional(),
+    expectedOutcome: expectedOutcomeSchema.optional(),
+    captureOnFailure: z.boolean().optional(),
+    disabled: z.boolean().optional(),
+    section: z.string().min(1).optional(),
+    postActions: z.array(flowActionNodeSchema).optional()
+}).strict();
+export const flowNodeSchema = z.lazy(() => z.discriminatedUnion("type", [
+    flowApiOperationNodeSchema,
+    flowDbQueryNodeSchema,
+    flowDbAssertNodeSchema,
+    flowDbExecuteNodeSchema,
+    flowUnixBatchNodeSchema,
+    z.object({
+        ...actionBase,
+        type: z.literal("parallel"),
+        branches: z.array(z.object({
+            id,
+            label: z.string().min(1).optional(),
+            nodes: z.array(flowNodeSchema)
+        }).strict()).min(1),
+        join: parallelJoinModeSchema.optional()
+    }).strict(),
+    z.object({
+        ...actionBase,
+        type: z.literal("loop"),
+        loop: loopSpecSchema,
+        nodes: z.array(flowNodeSchema).min(1)
+    }).strict()
+]));
+export const flowFileSchema = z.object({
+    version: z.literal(1),
+    id,
+    name: z.string().min(1).optional(),
+    environment: z.string().min(1),
+    variables: mappingObject.optional(),
+    environmentInputs: z.record(environmentInputSetSchema).optional(),
+    nodes: z.array(flowNodeSchema),
+    edges: z.array(z.object({
+        from: id,
+        to: id
+    }).strict()).optional(),
+    ui: z.object({
+        positions: z.record(z.object({
+            x: z.number(),
+            y: z.number()
+        }).strict()).optional(),
+        manualEdges: z.boolean().optional()
+    }).strict().optional()
+}).strict();

package/dist/flows/types.js

@@ -0,0 +1 @@
+export {};