adfinem 0.0.0 → 0.1.1

package/dist/config/secrets.js

@@ -0,0 +1,123 @@
+const secretKeyFragments = [
+    "password",
+    "passwd",
+    "pwd",
+    "token",
+    "authorization",
+    "apikey",
+    "api_key",
+    "privatekey",
+    "private_key",
+    "jwt",
+    "secret",
+    "credential",
+    "bearer",
+    "access_token",
+    "refreshtoken",
+    "refresh_token",
+    "servicepassword",
+    "apikey",
+    "session",
+    "cookie",
+    "pin",
+    "cvv",
+    "cvc",
+    "cvv2"
+];
+const cardKeyExact = new Set([
+    "pan",
+    "pans",
+    "cardnumber",
+    "cardnumbers",
+    "cardno",
+    "primaryaccountnumber",
+    "primaryaccountnumbers"
+]);
+const REDACTED = "<redacted>";
+export function redactSecrets(value) {
+    return redact(value);
+}
+export function evidenceVisibilityMode() {
+    return process.env.ADFINEM_EVIDENCE_VISIBILITY?.toLowerCase() === "redacted" ? "redacted" : "raw";
+}
+export function applyEvidenceVisibility(value, mode = evidenceVisibilityMode()) {
+    return mode === "redacted" ? redactSecrets(value) : value;
+}
+/**
+ * Heavier redaction intended for shared evidence artifacts.
+ * Combines key-based redaction with inline PAN-pattern scrubbing on every string.
+ */
+export function redactEvidence(value) {
+    return redactDeep(value, true);
+}
+export function maskInlinePans(text) {
+    if (!text)
+        return text;
+    return text.replace(/(?<!\d)(\d[\d\s.-]{10,21}\d)(?!\d)/g, (match) => {
+        const digits = match.replace(/\D+/g, "");
+        if (digits.length < 12 || digits.length > 19)
+            return match;
+        if (!isLuhnValid(digits))
+            return match;
+        return `****${digits.slice(-4)}`;
+    });
+}
+export function isLuhnValid(digits) {
+    if (!/^\d+$/.test(digits))
+        return false;
+    let sum = 0;
+    let alt = false;
+    for (let index = digits.length - 1; index >= 0; index--) {
+        let n = digits.charCodeAt(index) - 48;
+        if (alt) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        alt = !alt;
+    }
+    return sum > 0 && sum % 10 === 0;
+}
+function redact(value) {
+    return redactDeep(value, false);
+}
+function redactDeep(value, scrubStrings) {
+    if (typeof value === "string")
+        return scrubStrings ? maskInlinePans(value) : value;
+    if (Array.isArray(value))
+        return value.map((entry) => redactDeep(entry, scrubStrings));
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => {
+        const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+        if (secretKeyFragments.some((fragment) => normalized.includes(fragment))) {
+            return [key, REDACTED];
+        }
+        if (cardKeyExact.has(normalized)) {
+            return [key, maskCardLike(entry, scrubStrings)];
+        }
+        return [key, redactDeep(entry, scrubStrings)];
+    }));
+}
+function maskCardLike(value, scrubStrings) {
+    if (Array.isArray(value))
+        return value.map((entry) => maskCardLike(entry, scrubStrings));
+    if (typeof value === "string" || typeof value === "number") {
+        return maskPan(String(value));
+    }
+    if (value && typeof value === "object") {
+        return redactDeep(value, scrubStrings);
+    }
+    return value;
+}
+function maskPan(value) {
+    const digits = value.replace(/\D+/g, "");
+    if (digits.length < 12)
+        return value;
+    if (digits.length >= 12 && digits.length <= 19) {
+        return `${digits.slice(0, 4)}${"*".repeat(Math.max(4, digits.length - 8))}${digits.slice(-4)}`;
+    }
+    const last4 = digits.slice(-4);
+    return `****${last4}`;
+}

package/dist/dsl/parser.js

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+import YAML from "yaml";
+import { scenarioSchema, queryCatalogSchema, batchCatalogSchema, apiOperationsCatalogSchema } from "./schema.js";
+import { importedOperationsFromCollections, loadApiCollections } from "../adapters/api/api-collections.js";
+import { normalizeQueryCatalog } from "../adapters/db/query-catalog.js";
+export async function loadYamlFile(path) {
+    const raw = await readFile(path, "utf8");
+    return YAML.parse(raw);
+}
+export async function loadScenario(path) {
+    const parsed = await loadYamlFile(path);
+    return scenarioSchema.parse(parsed);
+}
+export async function loadCatalogs(rootDir) {
+    const queries = normalizeQueryCatalog(queryCatalogSchema.parse(await loadYamlFile(`${rootDir}/catalogs/queries.yaml`)));
+    const batches = batchCatalogSchema.parse(await loadYamlFile(`${rootDir}/catalogs/batches.yaml`));
+    const apiOperations = apiOperationsCatalogSchema.parse(await loadYamlFile(`${rootDir}/catalogs/api-operations.yaml`));
+    const importedApiOperations = importedOperationsFromCollections(await loadApiCollections(rootDir));
+    return { queries, batches, apiOperations: { ...apiOperations, ...importedApiOperations } };
+}

package/dist/dsl/schema.js

@@ -0,0 +1,182 @@
+import { z } from "zod";
+const value = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const catalogParamType = z.enum(["string", "number", "boolean", "string[]", "number[]", "boolean[]"]);
+const apiMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+const apiBodyMode = z.enum(["none", "json", "raw", "formdata", "urlencoded"]);
+const apiRequestSpecSchema = z.object({
+    method: apiMethod.optional(),
+    path: z.string().optional(),
+    headers: z.record(z.string()).optional(),
+    query: z.record(z.unknown()).optional(),
+    body: z.unknown().optional(),
+    rawBody: z.string().optional(),
+    bodyMode: apiBodyMode.optional(),
+    auth: z.unknown().optional(),
+    acceptStatuses: z.array(z.number().int().min(100).max(599)).optional()
+}).strict();
+const apiAssertionSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("status"),
+        operator: z.enum(["in", "="]).optional(),
+        value: z.union([z.number().int().min(100).max(599), z.array(z.number().int().min(100).max(599))])
+    }).strict(),
+    z.object({ type: z.literal("jsonpath_exists"), path: z.string().min(1) }).strict(),
+    z.object({ type: z.literal("jsonpath_equals"), path: z.string().min(1), value: z.unknown() }).strict(),
+    z.object({ type: z.literal("jsonpath_contains"), path: z.string().min(1), value: z.unknown() }).strict(),
+    z.object({ type: z.literal("header_exists"), header: z.string().min(1) }).strict(),
+    z.object({ type: z.literal("header_equals"), header: z.string().min(1), value: z.string() }).strict(),
+    z.object({ type: z.literal("body_contains"), value: z.string() }).strict(),
+    z.object({ type: z.literal("body_not_contains"), value: z.string() }).strict()
+]);
+const expectedOutcomeSchema = z.enum(["positive", "negative", "setup", "teardown"]);
+const parallelJoinModeSchema = z.enum(["all", "any", "fail_fast"]);
+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: z.unknown().optional(),
+    itemName: z.string().min(1).optional(),
+    maxIterations: z.number().int().positive().optional(),
+    dateCursor: loopDateCursorSchema.optional()
+}).strict();
+const catalogParamSchema = z.object({
+    required: z.boolean().optional(),
+    type: catalogParamType.optional(),
+    pattern: z.string().optional(),
+    luhn: z.boolean().optional()
+}).strict();
+const batchInputFileSchema = z.object({
+    name: z.string().min(1),
+    required: z.boolean().optional(),
+    remotePath: z.string().min(1).optional(),
+    paramName: z.string().min(1).optional(),
+    appendAsArg: z.boolean().optional()
+}).strict();
+const batchOutputFileSchema = z.object({
+    name: z.string().min(1),
+    required: z.boolean().optional(),
+    source: z.enum(["stdout", "stderr", "both", "explicit"]).optional(),
+    pathPattern: z.string().min(1).optional(),
+    remotePath: z.string().min(1).optional(),
+    download: z.boolean().optional(),
+    decrypt: z.object({
+        command: z.string().min(1).optional(),
+        outputRemotePath: z.string().min(1).optional(),
+        required: z.boolean().optional()
+    }).strict().optional()
+}).strict();
+export const scenarioStepSchema = z.lazy(() => z.object({
+    id: z.string().min(1).regex(/^[A-Za-z0-9_-]+$/),
+    action: z.string().min(1),
+    via: z.string().optional(),
+    retry: z.object({
+        attempts: z.number().int().positive().optional(),
+        delaySeconds: z.number().nonnegative().optional()
+    }).strict().optional(),
+    input: z.record(z.unknown()).optional(),
+    params: z.record(z.unknown()).optional(),
+    query: z.string().optional(),
+    batch: z.string().optional(),
+    request: apiRequestSpecSchema.optional(),
+    assertions: z.array(apiAssertionSchema).optional(),
+    capture: z.record(z.string()).optional(),
+    continueOnFailure: z.boolean().optional(),
+    expectedOutcome: expectedOutcomeSchema.optional(),
+    captureOnFailure: z.boolean().optional(),
+    control: z.enum(["parallel", "loop"]).optional(),
+    branches: z.array(z.object({
+        id: z.string().min(1).regex(/^[A-Za-z0-9_-]+$/),
+        label: z.string().min(1).optional(),
+        steps: z.array(scenarioStepSchema)
+    }).strict()).optional(),
+    steps: z.array(scenarioStepSchema).optional(),
+    loop: loopSpecSchema.optional(),
+    join: parallelJoinModeSchema.optional()
+}).strict());
+export const scenarioSchema = z.object({
+    id: z.string().min(1).regex(/^[A-Za-z0-9_-]+$/),
+    environment: z.string().min(1),
+    tenant: z.record(z.string()).optional(),
+    variables: z.record(z.union([value, z.array(value), z.record(value)])).optional(),
+    steps: z.array(scenarioStepSchema).min(1)
+}).strict();
+export const queryCatalogSchema = z.record(z.object({
+    description: z.string().optional(),
+    mode: z.enum(["query", "execute"]).optional(),
+    sql: z.string().min(1),
+    params: z.record(catalogParamSchema).optional(),
+    expect: z.object({
+        type: z.enum(["number", "string", "boolean", "rowCount"]),
+        column: z.string().optional(),
+        operator: z.enum(["=", "!=", ">", ">=", "<", "<=", "contains"]),
+        value: z.unknown()
+    }).strict()
+        .refine((expect) => expect.type === "rowCount" || Boolean(expect.column), {
+        message: "expect.column is required when expect.type is not rowCount."
+    })
+        .optional(),
+    captures: z.record(z.string()).optional(),
+    maxRows: z.number().int().positive().optional()
+}).strict());
+export const batchCatalogSchema = z.record(z.object({
+    description: z.string().optional(),
+    hostRef: z.string().min(1),
+    command: z.string().min(1).refine((value) => !/[\r\n]/.test(value), {
+        message: "command must be a single executable token; put arguments in fixedArgs."
+    }),
+    fixedArgs: z.array(z.union([z.string(), z.number(), z.boolean()])).optional(),
+    workingDirectory: z.string().min(1).optional(),
+    useWorkingDirectory: z.boolean().optional(),
+    environment: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    args: z.array(z.object({
+        name: z.string().min(1),
+        required: z.boolean().optional(),
+        type: catalogParamType.optional(),
+        pattern: z.string().optional(),
+        luhn: z.boolean().optional()
+    }).strict()).optional(),
+    inputFiles: z.array(batchInputFileSchema).optional(),
+    outputFiles: z.array(batchOutputFileSchema).optional(),
+    timeoutSeconds: z.number().int().positive().optional(),
+    success: z.object({
+        exitCodes: z.array(z.number().int()).optional(),
+        requiredOutput: z.array(z.string()).optional()
+    }).strict().optional(),
+    captures: z.record(z.string()).optional()
+}).strict());
+export const apiOperationsCatalogSchema = z.record(z.object({
+    description: z.string().optional(),
+    type: z.enum(["rest", "soap"]),
+    method: apiMethod.optional(),
+    path: z.string().optional(),
+    headers: z.record(z.string()).optional(),
+    query: z.record(z.unknown()).optional(),
+    body: z.unknown().optional(),
+    rawBody: z.string().optional(),
+    bodyMode: apiBodyMode.optional(),
+    auth: z.unknown().optional(),
+    params: z.record(catalogParamSchema).optional(),
+    assertions: z.array(apiAssertionSchema).optional(),
+    requestTemplate: z.string().optional(),
+    captures: z.record(z.string()).optional(),
+    acceptStatuses: z.array(z.number().int().min(100).max(599)).optional(),
+    idempotent: z.boolean().optional(),
+    source: z.object({
+        collectionId: z.string().optional(),
+        collectionName: z.string().optional(),
+        requestId: z.string().optional(),
+        folderPath: z.array(z.string()).optional()
+    }).strict().optional()
+}).strict());
+export { apiRequestSpecSchema, apiAssertionSchema };

package/dist/dsl/types.js

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

package/dist/dsl/validator.js

@@ -0,0 +1,264 @@
+import { registeredActions } from "../config/registry.js";
+import { normalizeBindParamRecord } from "../adapters/db/query-catalog.js";
+import { batchArgParamsForValidation, batchInputFiles, hasBatchInputFilePayload } from "../adapters/unix/batch-input-files.js";
+export function validateScenarioReferences(scenario, catalogs, options = {}) {
+    const errors = [];
+    const warnings = [];
+    if (options.knownEnvironments && options.knownEnvironments.length > 0
+        && !options.knownEnvironments.includes(scenario.environment)) {
+        warnings.push(`Scenario environment '${scenario.environment}' is not declared in config/environments.yaml. Known: ${options.knownEnvironments.join(", ")}.`);
+    }
+    const stepIds = new Set();
+    const availableVariables = new Set(Object.keys(scenario.variables ?? {}));
+    for (const key of Object.keys(scenario.tenant ?? {})) {
+        availableVariables.add(`tenant.${key}`);
+    }
+    for (const step of scenario.steps) {
+        if (step.control === "parallel" || step.action === "__parallel") {
+            validateControlStep(step, catalogs, errors, warnings, stepIds, availableVariables);
+            continue;
+        }
+        if (step.control === "loop" || step.action === "__loop") {
+            validateControlStep(step, catalogs, errors, warnings, stepIds, availableVariables);
+            const outputName = step.loop?.dateCursor?.outputName?.trim() || (step.loop?.dateCursor ? "business_date" : undefined);
+            if (outputName) {
+                availableVariables.add(outputName);
+                availableVariables.add(`${step.id}.${outputName}`);
+                availableVariables.add(`${step.id}.last.${outputName}`);
+                availableVariables.add(`${step.id}.all.${outputName}`);
+            }
+            for (const [childId, captureName] of loopChildCaptureNames(step, catalogs)) {
+                availableVariables.add(`${childId}.${captureName}`);
+                availableVariables.add(`${step.id}.last.${childId}.${captureName}`);
+                availableVariables.add(`${step.id}.all.${childId}.${captureName}`);
+            }
+            continue;
+        }
+        if (stepIds.has(step.id)) {
+            errors.push(`Duplicate step id '${step.id}'.`);
+        }
+        stepIds.add(step.id);
+        const action = registeredActions[step.action];
+        if (!action) {
+            if (step.via === "api" && catalogs.apiOperations[step.action]) {
+                validateApiStep(step, catalogs, errors);
+            }
+            else {
+                errors.push(`Step '${step.id}' uses unknown action '${step.action}'.`);
+                continue;
+            }
+        }
+        else if (step.via && !action.supportedVia.includes(step.via)) {
+            errors.push(`Step '${step.id}' action '${step.action}' does not support via '${step.via}'. Supported: ${action.supportedVia.join(", ")}.`);
+        }
+        if (step.action === "db_assert" || step.action === "db_query" || step.action === "db_execute") {
+            if (!step.query)
+                errors.push(`Step '${step.id}' must specify query.`);
+            if (step.query && !catalogs.queries[step.query])
+                errors.push(`Step '${step.id}' references unknown query '${step.query}'.`);
+            if (step.action === "db_assert" && step.query && catalogs.queries[step.query] && !catalogs.queries[step.query].expect) {
+                errors.push(`Step '${step.id}' uses db_assert but query '${step.query}' has no expect block.`);
+            }
+            if (step.action === "db_execute" && step.query && catalogs.queries[step.query]?.mode !== "execute") {
+                errors.push(`Step '${step.id}' uses db_execute but query '${step.query}' is not marked mode: execute.`);
+            }
+            if (step.query && catalogs.queries[step.query]) {
+                validateParams(step, normalizeBindParamRecord(catalogs.queries[step.query].params ?? {}), normalizeBindParamRecord(step.params ?? step.input ?? {}), errors, "query");
+            }
+        }
+        if (step.action === "unix_batch") {
+            if (!step.batch)
+                errors.push(`Step '${step.id}' must specify batch.`);
+            if (step.batch && !catalogs.batches[step.batch])
+                errors.push(`Step '${step.id}' references unknown batch '${step.batch}'.`);
+            if (step.batch && catalogs.batches[step.batch]) {
+                const batch = catalogs.batches[step.batch];
+                const params = step.params ?? step.input ?? {};
+                validateBatchInputFiles(step, batch, params, errors);
+                validateArgs(step, batch.args ?? [], batchArgParamsForValidation(params, batch), errors);
+            }
+        }
+        if (step.via === "api")
+            validateApiStep(step, catalogs, errors);
+        const localVariables = new Set(Object.keys(step.input ?? step.params ?? {}));
+        for (const variable of findVariableRefs(step)) {
+            if (!availableVariables.has(variable) && !localVariables.has(variable)) {
+                errors.push(`Step '${step.id}' references unknown variable '${variable}'.`);
+            }
+        }
+        const apiCatalogCaptures = step.via === "api" ? catalogs.apiOperations[step.action]?.captures ?? {} : {};
+        const queryCatalogCaptures = step.query ? catalogs.queries[step.query]?.captures ?? {} : {};
+        const batchCatalogCaptures = step.batch ? catalogs.batches[step.batch]?.captures ?? {} : {};
+        for (const captureName of [
+            ...Object.keys(apiCatalogCaptures),
+            ...Object.keys(queryCatalogCaptures),
+            ...Object.keys(batchCatalogCaptures),
+            ...Object.keys(step.capture ?? {})
+        ]) {
+            availableVariables.add(captureName);
+            availableVariables.add(`${step.id}.${captureName}`);
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings: warnings.length ? warnings : undefined };
+}
+function validateApiStep(step, catalogs, errors) {
+    const operation = catalogs.apiOperations[step.action];
+    if (!operation) {
+        errors.push(`Step '${step.id}' uses via api but no API operation '${step.action}' exists in api-operations.yaml.`);
+        return;
+    }
+    validateParams(step, operation.params, step.input ?? step.params ?? {}, errors, "API variable");
+}
+function validateControlStep(step, catalogs, errors, warnings, stepIds, availableVariables) {
+    if (stepIds.has(step.id))
+        errors.push(`Duplicate step id '${step.id}'.`);
+    stepIds.add(step.id);
+    if (step.control === "parallel" || step.action === "__parallel") {
+        if (!step.branches?.length)
+            errors.push(`Parallel step '${step.id}' must contain at least one branch.`);
+        for (const branch of step.branches ?? []) {
+            const nested = validateScenarioReferences({ id: `${step.id}_${branch.id}`, environment: "nested", variables: Object.fromEntries([...availableVariables].map((key) => [key, "available"])), steps: branch.steps }, catalogs);
+            errors.push(...nested.errors.map((error) => `Parallel '${step.id}' branch '${branch.id}': ${error}`));
+            warnings.push(...(nested.warnings ?? []).map((warning) => `Parallel '${step.id}' branch '${branch.id}': ${warning}`));
+        }
+    }
+    if (step.control === "loop" || step.action === "__loop") {
+        if (!step.steps?.length)
+            errors.push(`Loop step '${step.id}' must contain at least one child step.`);
+        if (step.loop?.mode === "count" && step.loop.count === undefined)
+            errors.push(`Loop step '${step.id}' mode count requires loop.count.`);
+        if (step.loop?.mode === "foreach" && step.loop.items === undefined)
+            errors.push(`Loop step '${step.id}' mode foreach requires loop.items.`);
+        const loopVariables = new Set(availableVariables);
+        loopVariables.add(`${step.id}.index`);
+        loopVariables.add(`${step.id}.number`);
+        loopVariables.add(`${step.id}.total`);
+        loopVariables.add(`${step.id}.item`);
+        if (step.loop?.itemName) {
+            loopVariables.add(step.loop.itemName);
+            loopVariables.add(`${step.id}.${step.loop.itemName}`);
+        }
+        const outputName = step.loop?.dateCursor?.outputName?.trim() || (step.loop?.dateCursor ? "business_date" : undefined);
+        if (outputName) {
+            loopVariables.add(outputName);
+            loopVariables.add(`${step.id}.${outputName}`);
+            loopVariables.add(`${step.id}.last.${outputName}`);
+            loopVariables.add(`${step.id}.all.${outputName}`);
+        }
+        const nested = validateScenarioReferences({ id: `${step.id}_loop`, environment: "nested", variables: Object.fromEntries([...loopVariables].map((key) => [key, "available"])), steps: step.steps ?? [] }, catalogs);
+        errors.push(...nested.errors.map((error) => `Loop '${step.id}': ${error}`));
+        warnings.push(...(nested.warnings ?? []).map((warning) => `Loop '${step.id}': ${warning}`));
+    }
+}
+function loopChildCaptureNames(step, catalogs) {
+    const captures = [];
+    const visit = (child) => {
+        const catalogCaptures = child.via === "api"
+            ? catalogs.apiOperations[child.action]?.captures ?? {}
+            : child.query
+                ? catalogs.queries[child.query]?.captures ?? {}
+                : child.batch
+                    ? catalogs.batches[child.batch]?.captures ?? {}
+                    : {};
+        for (const captureName of [...Object.keys(catalogCaptures), ...Object.keys(child.capture ?? {})]) {
+            captures.push([child.id, captureName]);
+        }
+        if (child.control === "loop" || child.action === "__loop") {
+            for (const nested of child.steps ?? [])
+                visit(nested);
+        }
+        if (child.control === "parallel" || child.action === "__parallel") {
+            for (const branch of child.branches ?? []) {
+                for (const nested of branch.steps)
+                    visit(nested);
+            }
+        }
+    };
+    for (const child of step.steps ?? [])
+        visit(child);
+    return captures;
+}
+function validateParams(step, specs, params, errors, label) {
+    for (const [name, spec] of Object.entries(specs ?? {})) {
+        const value = params[name];
+        if (spec.required && (value === undefined || value === null || value === "")) {
+            errors.push(`Step '${step.id}' is missing required ${label} param '${name}'.`);
+            continue;
+        }
+        validateValue(step.id, name, value, spec, errors);
+    }
+}
+function validateArgs(step, specs, params, errors) {
+    for (const spec of specs) {
+        if (!Object.prototype.hasOwnProperty.call(params, spec.name))
+            continue;
+        const value = params[spec.name];
+        if (spec.required !== false && (value === undefined || value === null || value === "")) {
+            errors.push(`Step '${step.id}' is missing required batch arg '${spec.name}'.`);
+            continue;
+        }
+        validateValue(step.id, spec.name, value, spec, errors);
+    }
+}
+function validateBatchInputFiles(step, batch, params, errors) {
+    for (const file of batchInputFiles(batch)) {
+        const value = params[file.name];
+        if (file.required !== false && !hasBatchInputFilePayload(value)) {
+            errors.push(`Step '${step.id}' is missing required batch input file '${file.name}'.`);
+        }
+        const remotePath = value && typeof value === "object" && !Array.isArray(value)
+            ? value.remotePath
+            : undefined;
+        if (hasBatchInputFilePayload(value) && !file.remotePath && !remotePath) {
+            errors.push(`Step '${step.id}' batch input file '${file.name}' needs a remote path.`);
+        }
+    }
+}
+function validateValue(stepId, name, value, spec, errors) {
+    if (value === undefined || value === null)
+        return;
+    if (typeof value === "string" && /^\$\{[A-Za-z0-9_.-]+\}$/.test(value))
+        return;
+    if (spec.type?.endsWith("[]")) {
+        const expectedItemType = spec.type.slice(0, -"[]".length);
+        const values = Array.isArray(value) ? value : [value];
+        if (values.length === 0) {
+            errors.push(`Step '${stepId}' param '${name}' must contain at least one value.`);
+            return;
+        }
+        for (const item of values) {
+            if (typeof item !== expectedItemType) {
+                errors.push(`Step '${stepId}' param '${name}' must be ${spec.type}; got ${typeof item} item.`);
+            }
+            if (spec.pattern && typeof item === "string" && !new RegExp(spec.pattern).test(item)) {
+                errors.push(`Step '${stepId}' param '${name}' does not match ${spec.pattern}.`);
+            }
+        }
+        return;
+    }
+    if (spec.type && typeof value !== spec.type) {
+        errors.push(`Step '${stepId}' param '${name}' must be ${spec.type}; got ${typeof value}.`);
+    }
+    if (spec.pattern && typeof value === "string" && !new RegExp(spec.pattern).test(value)) {
+        errors.push(`Step '${stepId}' param '${name}' does not match ${spec.pattern}.`);
+    }
+}
+function findVariableRefs(value) {
+    const refs = [];
+    const visit = (current) => {
+        if (typeof current === "string") {
+            for (const match of current.matchAll(/\$\{([A-Za-z0-9_.-]+)\}/g))
+                refs.push(match[1]);
+            for (const match of current.matchAll(/\{\{([A-Za-z0-9_.-]+)\}\}/g))
+                refs.push(match[1]);
+        }
+        else if (Array.isArray(current)) {
+            current.forEach(visit);
+        }
+        else if (current && typeof current === "object") {
+            Object.values(current).forEach(visit);
+        }
+    };
+    visit(value);
+    return refs;
+}

package/dist/engine/captures.js

@@ -0,0 +1,68 @@
+import { JSONPath } from "jsonpath-plus";
+export function extractCaptures(payload, specs) {
+    const captures = {};
+    for (const [name, expression] of Object.entries(specs ?? {})) {
+        const value = extractCaptureValue(payload, expression);
+        if (value !== undefined)
+            captures[name] = value;
+    }
+    return captures;
+}
+export function mergeCaptureSpecs(...specs) {
+    return Object.assign({}, ...specs.filter(Boolean));
+}
+function extractCaptureValue(payload, expression) {
+    const { expression: trimmed, required } = parseCaptureExpression(expression);
+    if (!trimmed)
+        throw new Error("Capture expression must not be empty.");
+    try {
+        if (trimmed.startsWith("literal:"))
+            return trimmed.slice("literal:".length);
+        if (trimmed.startsWith("regex:"))
+            return extractRegexCapture(payload, trimmed);
+        return extractJsonPathCapture(payload, normalizeJsonPath(trimmed), trimmed);
+    }
+    catch (error) {
+        if (!required && isCaptureNoMatch(error))
+            return undefined;
+        throw error;
+    }
+}
+function parseCaptureExpression(expression) {
+    const trimmed = expression.trim();
+    if (trimmed.startsWith("optional:")) {
+        return { expression: trimmed.slice("optional:".length).trim(), required: false };
+    }
+    return { expression: trimmed, required: true };
+}
+function extractJsonPathCapture(payload, jsonPath, original) {
+    const json = payload;
+    const values = JSONPath({ path: jsonPath, json, wrap: true });
+    if (values.length === 0)
+        throw new Error(`Capture expression '${original}' did not match any value.`);
+    return values.length === 1 ? values[0] : values;
+}
+function extractRegexCapture(payload, expression) {
+    const parts = expression.split(":");
+    if (parts.length < 3) {
+        throw new Error(`Invalid regex capture '${expression}'. Use regex:<jsonpath>:<pattern>.`);
+    }
+    const sourcePath = parts[1]?.trim() || "$";
+    const pattern = parts.slice(2).join(":");
+    const source = extractJsonPathCapture(payload, normalizeJsonPath(sourcePath), sourcePath);
+    const match = String(source ?? "").match(new RegExp(pattern, "m"));
+    if (!match)
+        throw new Error(`Regex capture '${expression}' did not match.`);
+    return match[1] ?? match[0];
+}
+function normalizeJsonPath(expression) {
+    if (expression.startsWith("$"))
+        return expression;
+    if (/^[A-Za-z_][A-Za-z0-9_]*(?:[.[].*)?$/.test(expression))
+        return `$.${expression}`;
+    throw new Error(`Unsupported capture expression '${expression}'. Use JSONPath, simple property path, literal:, or regex:.`);
+}
+function isCaptureNoMatch(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /did not match any value|did not match\./i.test(message);
+}