adfinem 0.0.0 → 0.1.0

package/dist/adapters/db/oracle-client.js

@@ -0,0 +1,115 @@
+import { assertQueryResult } from "./assertions.js";
+import { normalizeBindParamRecord, validateQueryParams } from "./query-catalog.js";
+export class OracleClient {
+    env;
+    constructor(env) {
+        this.env = env;
+    }
+    async query(entry, params) {
+        const bindParams = normalizeBindParamRecord(params);
+        validateQueryParams(entry, bindParams);
+        if (!this.env.oracle.user || !this.env.oracle.password || !this.env.oracle.connectString) {
+            throw new Error("ADFINEM_DB_USER, ADFINEM_DB_PASSWORD, and ADFINEM_DB_CONNECT_STRING are required for DB execution.");
+        }
+        const oracledb = await loadOracleDbModule();
+        const connection = await oracledb.getConnection(this.env.oracle);
+        try {
+            const prepared = expandArrayBinds(entry.sql, bindParams);
+            const result = await connection.execute(prepared.sql, prepared.binds, { outFormat: oracledb.OUT_FORMAT_OBJECT });
+            return limitRows(result.rows ?? [], entry.maxRows);
+        }
+        finally {
+            await closeQuietly(connection);
+        }
+    }
+    async assert(entry, params) {
+        const rows = await this.query(entry, params);
+        assertQueryResult(entry, rows);
+        return rows;
+    }
+    async execute(entry, params) {
+        const bindParams = normalizeBindParamRecord(params);
+        validateQueryParams(entry, bindParams);
+        if (!this.env.oracle.user || !this.env.oracle.password || !this.env.oracle.connectString) {
+            throw new Error("ADFINEM_DB_USER, ADFINEM_DB_PASSWORD, and ADFINEM_DB_CONNECT_STRING are required for DB execution.");
+        }
+        const oracledb = await loadOracleDbModule();
+        const connection = await oracledb.getConnection(this.env.oracle);
+        try {
+            const prepared = expandArrayBinds(entry.sql, bindParams);
+            const result = await connection.execute(prepared.sql, prepared.binds, {
+                outFormat: oracledb.OUT_FORMAT_OBJECT,
+                autoCommit: true
+            });
+            const execution = result;
+            return {
+                status: "passed",
+                rowsAffected: execution.rowsAffected,
+                outBinds: execution.outBinds
+            };
+        }
+        finally {
+            await closeQuietly(connection);
+        }
+    }
+}
+async function closeQuietly(connection) {
+    try {
+        await connection.close();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // Connection close failures must not mask the operation error from the surrounding try.
+        console.warn(`Oracle connection close failed: ${message}`);
+    }
+}
+let oracleDbModule;
+async function loadOracleDbModule() {
+    if (oracleDbModule)
+        return oracleDbModule;
+    try {
+        const imported = await import("oracledb");
+        oracleDbModule = normalizeOracleDbModule(imported);
+        return oracleDbModule;
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        throw new Error(`Could not load optional dependency 'oracledb'. Run 'npm install' and ensure Oracle client libraries are available. Original error: ${err.message}`);
+    }
+}
+function normalizeOracleDbModule(imported) {
+    const moduleValue = imported;
+    const candidate = typeof moduleValue.getConnection === "function" ? moduleValue : moduleValue.default;
+    if (!candidate || typeof candidate.getConnection !== "function") {
+        throw new Error("Loaded 'oracledb', but it did not expose getConnection().");
+    }
+    return candidate;
+}
+function limitRows(rows, maxRows) {
+    if (maxRows === undefined)
+        return rows;
+    return rows.slice(0, maxRows);
+}
+function expandArrayBinds(sql, params) {
+    const binds = {};
+    let expandedSql = sql;
+    for (const [name, value] of Object.entries(params)) {
+        if (!Array.isArray(value)) {
+            binds[name] = value;
+            continue;
+        }
+        if (value.length === 0) {
+            throw new Error(`Query param '${name}' must contain at least one value.`);
+        }
+        const placeholders = value.map((entry, index) => {
+            const bindName = `${name}_${index}`;
+            binds[bindName] = entry;
+            return `:${bindName}`;
+        });
+        expandedSql = expandedSql.replace(new RegExp(`:${escapeRegExp(name)}\\b`, "g"), placeholders.join(", "));
+    }
+    return { sql: expandedSql, binds };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/adapters/db/query-catalog.js

@@ -0,0 +1,75 @@
+import { isLuhnValid } from "../../config/secrets.js";
+export function validateQueryParams(entry, params) {
+    const specs = normalizeBindParamRecord(entry.params ?? {});
+    const normalizedParams = normalizeBindParamRecord(params);
+    for (const [name, spec] of Object.entries(specs)) {
+        const value = normalizedParams[name];
+        if (spec.required && (value === undefined || value === null || value === "")) {
+            throw new Error(`Missing required query param '${name}'.`);
+        }
+        validateParamValue(name, value, spec);
+    }
+}
+export function normalizeQueryCatalog(queries) {
+    return Object.fromEntries(Object.entries(queries).map(([id, entry]) => [id, normalizeQueryCatalogEntry(entry)]));
+}
+export function normalizeQueryCatalogEntry(entry) {
+    return {
+        ...entry,
+        params: entry.params ? normalizeBindParamRecord(entry.params) : undefined
+    };
+}
+export function normalizeBindParamRecord(value) {
+    const normalized = {};
+    for (const [name, entry] of Object.entries(value)) {
+        const bindName = normalizeBindParamName(name);
+        if (bindName)
+            normalized[bindName] = entry;
+    }
+    return normalized;
+}
+export function normalizeBindParamName(name) {
+    return String(name ?? "").trim().replace(/^:+/, "");
+}
+function validateParamValue(name, value, spec) {
+    if (value === undefined || value === null)
+        return;
+    if (spec.type?.endsWith("[]")) {
+        const expectedItemType = spec.type.slice(0, -"[]".length);
+        const values = Array.isArray(value) ? value : [value];
+        if (values.length === 0)
+            throw new Error(`Query param '${name}' must contain at least one value.`);
+        for (const item of values) {
+            if (typeof item !== expectedItemType) {
+                throw new Error(`Query param '${name}' must be ${spec.type}; got ${typeof item} item.`);
+            }
+            validatePattern(name, item, spec);
+            validateLuhn(name, item, spec);
+        }
+        return;
+    }
+    if (spec.type && typeof value !== spec.type) {
+        throw new Error(`Query param '${name}' must be ${spec.type}; got ${typeof value}.`);
+    }
+    validatePattern(name, value, spec);
+    validateLuhn(name, value, spec);
+}
+function validatePattern(name, value, spec) {
+    if (spec.pattern && typeof value === "string" && !new RegExp(spec.pattern).test(value)) {
+        throw new Error(`Query param '${name}' does not match ${spec.pattern}.`);
+    }
+}
+function validateLuhn(name, value, spec) {
+    if (!spec.luhn)
+        return;
+    if (typeof value !== "string" && typeof value !== "number") {
+        throw new Error(`Query param '${name}' must be a string or number for Luhn validation.`);
+    }
+    const digits = String(value).replace(/\D+/g, "");
+    if (digits.length < 12 || digits.length > 19) {
+        throw new Error(`Query param '${name}' must be 12-19 digits for Luhn validation.`);
+    }
+    if (!isLuhnValid(digits)) {
+        throw new Error(`Query param '${name}' fails Luhn check.`);
+    }
+}

package/dist/adapters/unix/batch-catalog.js

@@ -0,0 +1,71 @@
+export function buildBatchCommand(entry, params) {
+    return buildBatchCommandDetails(entry, params).command;
+}
+export function buildBatchDisplayCommand(entry, params) {
+    return buildBatchCommandDetails(entry, params).displayCommand;
+}
+export function buildBatchCommandDetails(entry, params, extraArgs = []) {
+    const fixedArgs = (entry.fixedArgs ?? []).map((value) => resolvePlaceholders(String(value), params));
+    const args = (entry.args ?? []).map((arg) => {
+        const hasValue = Object.prototype.hasOwnProperty.call(params, arg.name);
+        const value = params[arg.name];
+        if (!hasValue || value === undefined || value === null) {
+            return undefined;
+        }
+        if (value === "") {
+            if (arg.required === false)
+                return undefined;
+            throw new Error(`Missing required batch arg '${arg.name}'.`);
+        }
+        if (arg.pattern && !new RegExp(arg.pattern).test(String(value))) {
+            throw new Error(`Batch arg '${arg.name}' does not match ${arg.pattern}.`);
+        }
+        return resolvePlaceholders(String(value), params);
+    }).filter((value) => Boolean(value));
+    const appendedArgs = extraArgs.map((value) => resolvePlaceholders(String(value), params));
+    const commandTokens = [resolvePlaceholders(entry.command, params), ...fixedArgs, ...args, ...appendedArgs];
+    const command = commandTokens.map(shellQuote).join(" ");
+    const displayCommand = commandTokens.map(displayToken).join(" ");
+    const envEntries = Object.entries(entry.environment ?? {})
+        .map(([name, value]) => [name, resolvePlaceholders(String(value), params)]);
+    const envPrefix = envEntries
+        .map(([name, value]) => `${name}=${shellQuote(value)}`)
+        .join(" ");
+    const displayEnvPrefix = envEntries
+        .map(([name, value]) => `${name}=${displayToken(value)}`)
+        .join(" ");
+    const commandWithEnv = envPrefix ? `${envPrefix} ${command}` : command;
+    const displayCommandWithEnv = displayEnvPrefix ? `${displayEnvPrefix} ${displayCommand}` : displayCommand;
+    const workingDirectory = entry.useWorkingDirectory === true
+        ? blankToUndefined(entry.workingDirectory ? resolvePlaceholders(entry.workingDirectory, params) : undefined)
+        : undefined;
+    return {
+        command: workingDirectory
+            ? `cd ${shellQuote(workingDirectory)} && ${commandWithEnv}`
+            : commandWithEnv,
+        displayCommand: workingDirectory
+            ? `cd ${displayToken(workingDirectory)} && ${displayCommandWithEnv}`
+            : displayCommandWithEnv
+    };
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function resolvePlaceholders(value, params) {
+    return value.replace(/\$\{([A-Za-z0-9_.-]+)\}/g, (_match, name) => {
+        const paramValue = params[name];
+        if (paramValue !== undefined && paramValue !== null)
+            return String(paramValue);
+        return process.env[name] ?? "";
+    });
+}
+function displayToken(value) {
+    if (value === "")
+        return "\"\"";
+    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(value))
+        return value;
+    return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+function blankToUndefined(value) {
+    return value && value.trim() ? value : undefined;
+}

package/dist/adapters/unix/batch-input-files.js

@@ -0,0 +1,36 @@
+export function batchInputFiles(entry) {
+    return entry?.inputFiles ?? [];
+}
+export function batchInputFileParamNames(entry) {
+    return batchInputFiles(entry).flatMap((file) => {
+        const names = [file.name];
+        if (file.paramName && file.paramName !== file.name)
+            names.push(file.paramName);
+        return names;
+    });
+}
+export function batchFileBackedArgNames(entry) {
+    return new Set(batchInputFiles(entry).map((file) => file.paramName || file.name));
+}
+export function isBatchInputFileValue(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+export function hasBatchInputFilePayload(value) {
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (!isBatchInputFileValue(value))
+        return false;
+    return Boolean(value.localPath || value.contentBase64);
+}
+export function batchArgParamsForValidation(params, entry) {
+    const next = { ...params };
+    for (const file of batchInputFiles(entry)) {
+        const value = params[file.name];
+        if (!hasBatchInputFilePayload(value))
+            continue;
+        next[file.paramName || file.name] = isBatchInputFileValue(value)
+            ? value.remotePath || file.remotePath || "__uploaded_input_file__"
+            : file.remotePath || "__uploaded_input_file__";
+    }
+    return next;
+}

package/dist/adapters/unix/batch-runner.js

@@ -0,0 +1,382 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { buildBatchCommandDetails } from "./batch-catalog.js";
+import { hasBatchInputFilePayload, isBatchInputFileValue } from "./batch-input-files.js";
+import { cancellationError, isCancellationError } from "../../engine/step-result.js";
+export class BatchRunner {
+    ssh;
+    rootDir;
+    constructor(ssh, rootDir = process.cwd()) {
+        this.ssh = ssh;
+        this.rootDir = rootDir;
+    }
+    async run(entry, params, options = {}) {
+        const uploadPlan = await this.uploadInputFiles(entry, params, options);
+        const { command, displayCommand } = buildBatchCommandDetails(entry, uploadPlan.params, uploadPlan.appendedArgs);
+        const maxAttempts = Math.max(1, options.attempts ?? 1);
+        const delayMs = Math.max(0, options.delayMs ?? 0);
+        const attempts = [];
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            if (options.signal?.aborted)
+                throw cancellationError();
+            const startedAt = new Date().toISOString();
+            try {
+                const result = await this.ssh.execute(entry.hostRef, command, (entry.timeoutSeconds ?? 3600) * 1000, options.signal);
+                const endedAt = new Date().toISOString();
+                const status = batchSucceeded(entry, result) ? "passed" : "failed";
+                const diagnostics = extractBatchDiagnostics(result.stdout, result.stderr);
+                const attemptResult = {
+                    attempt,
+                    startedAt,
+                    endedAt,
+                    command,
+                    displayCommand,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    exitCode: result.exitCode,
+                    tracePath: diagnostics.tracePath,
+                    errno: diagnostics.errno,
+                    stdoutTruncated: result.stdoutTruncated,
+                    stderrTruncated: result.stderrTruncated,
+                    status,
+                    error: status === "failed" ? batchFailureMessage(entry, result) : undefined
+                };
+                attempts.push(attemptResult);
+                if (status === "passed")
+                    break;
+            }
+            catch (error) {
+                if (isCancellationError(error))
+                    throw error;
+                const err = error instanceof Error ? error : new Error(String(error));
+                attempts.push({
+                    attempt,
+                    startedAt,
+                    endedAt: new Date().toISOString(),
+                    command,
+                    displayCommand,
+                    stdout: "",
+                    stderr: "",
+                    status: "failed",
+                    error: err.message
+                });
+            }
+            if (attempt < maxAttempts && delayMs > 0)
+                await sleep(delayMs, options.signal);
+        }
+        const summary = summarizeBatch(command, displayCommand, attempts, uploadPlan.fileUploads);
+        return await this.withOutputFiles(entry, uploadPlan.params, summary, options);
+    }
+    async uploadInputFiles(entry, params, options) {
+        const inputFiles = entry.inputFiles ?? [];
+        if (inputFiles.length === 0)
+            return { params, appendedArgs: [], fileUploads: undefined };
+        const commandParams = { ...params };
+        const appendedArgs = [];
+        const fileUploads = [];
+        const timeoutMs = Math.max(30_000, (entry.timeoutSeconds ?? 3600) * 1000);
+        for (const spec of inputFiles) {
+            const value = params[spec.name];
+            if (!hasBatchInputFilePayload(value)) {
+                if (spec.required !== false)
+                    throw new Error(`Batch input file '${spec.name}' is required.`);
+                continue;
+            }
+            const file = normalizeInputFileValue(value);
+            const fileName = file.fileName || (file.localPath ? basename(file.localPath) : spec.name);
+            const remotePath = resolveRemotePath(spec, file, commandParams, fileName);
+            const content = await readInputFileContent(this.rootDir, file);
+            const upload = {
+                name: spec.name,
+                fileName,
+                localPath: file.localPath,
+                remotePath,
+                sizeBytes: content.byteLength,
+                paramName: spec.paramName || spec.name,
+                appendedAsArg: spec.appendAsArg === true || undefined,
+                status: "uploaded"
+            };
+            try {
+                await this.ssh.uploadFile(entry.hostRef, remotePath, content, timeoutMs, options.signal);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                fileUploads.push({ ...upload, status: "failed", error: err.message });
+                throw new Error(`SFTP upload failed for batch input file '${spec.name}' to '${remotePath}': ${err.message}`);
+            }
+            fileUploads.push(upload);
+            commandParams[spec.paramName || spec.name] = remotePath;
+            if (spec.appendAsArg)
+                appendedArgs.push(remotePath);
+        }
+        return { params: commandParams, appendedArgs, fileUploads };
+    }
+    async withOutputFiles(entry, params, summary, options) {
+        const outputFiles = entry.outputFiles ?? [];
+        if (outputFiles.length === 0)
+            return summary;
+        const timeoutMs = Math.max(30_000, (entry.timeoutSeconds ?? 3600) * 1000);
+        const last = summary.attempts[summary.attempts.length - 1];
+        const fileDownloads = [];
+        for (const spec of outputFiles) {
+            fileDownloads.push(await this.retrieveOutputFile(entry, spec, params, last, timeoutMs, options));
+        }
+        const requiredFailure = fileDownloads.find((file) => file.status === "failed" && fileRequired(file.name, outputFiles));
+        if (requiredFailure && last) {
+            last.status = "failed";
+            last.error = requiredFailure.error ?? `Batch output file '${requiredFailure.name}' was not retrieved.`;
+            summary.status = "failed";
+        }
+        return { ...summary, fileDownloads };
+    }
+    async retrieveOutputFile(entry, spec, params, last, timeoutMs, options) {
+        const source = spec.source ?? (spec.remotePath ? "explicit" : "stderr");
+        const baseEvidence = { name: spec.name, source, status: "skipped" };
+        try {
+            const remotePath = resolveOutputRemotePath(spec, params, last);
+            if (!remotePath) {
+                if (spec.required === false)
+                    return { ...baseEvidence, status: "skipped", error: "No generated file path was found." };
+                return { ...baseEvidence, status: "failed", error: `Batch output file '${spec.name}' path was not found in ${source}.` };
+            }
+            const templateVars = outputTemplateVars(spec, remotePath, params);
+            const decryptCommandTemplate = spec.decrypt?.command?.trim();
+            let decryptCommand;
+            let downloadRemotePath = remotePath;
+            let decryptExitCode;
+            let decryptStdout;
+            let decryptStderr;
+            let decryptedRemotePath;
+            if (decryptCommandTemplate) {
+                decryptedRemotePath = resolveTemplate(spec.decrypt?.outputRemotePath || "${remotePath}.dec", {
+                    ...templateVars,
+                    decryptedRemotePath: `${remotePath}.dec`
+                });
+                decryptCommand = resolveTemplate(decryptCommandTemplate, {
+                    ...templateVars,
+                    decryptedRemotePath
+                });
+                const decrypt = await this.ssh.execute(entry.hostRef, decryptCommand, timeoutMs, options.signal);
+                decryptExitCode = decrypt.exitCode;
+                decryptStdout = decrypt.stdout;
+                decryptStderr = decrypt.stderr;
+                if (decrypt.exitCode !== 0 && spec.decrypt?.required !== false) {
+                    return {
+                        ...baseEvidence,
+                        remotePath,
+                        decryptCommand,
+                        decryptedRemotePath,
+                        decryptExitCode,
+                        decryptStdout,
+                        decryptStderr,
+                        status: "failed",
+                        error: `Decrypt command failed with exit code ${decrypt.exitCode}.`
+                    };
+                }
+                if (decrypt.exitCode === 0)
+                    downloadRemotePath = decryptedRemotePath;
+            }
+            if (spec.download === false) {
+                return {
+                    ...baseEvidence,
+                    remotePath,
+                    decryptCommand,
+                    decryptedRemotePath,
+                    decryptExitCode,
+                    decryptStdout,
+                    decryptStderr,
+                    status: "skipped"
+                };
+            }
+            if (!options.downloadDir) {
+                return { ...baseEvidence, remotePath: downloadRemotePath, status: "failed", error: "No local evidence download directory was configured." };
+            }
+            const content = await this.ssh.downloadFile(entry.hostRef, downloadRemotePath, timeoutMs, options.signal);
+            const localPath = await writeDownloadedFile(options.downloadDir, spec.name, downloadRemotePath, content);
+            return {
+                ...baseEvidence,
+                remotePath,
+                localPath,
+                sizeBytes: content.byteLength,
+                decryptCommand,
+                decryptedRemotePath,
+                decryptExitCode,
+                decryptStdout,
+                decryptStderr,
+                status: "downloaded"
+            };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            return { ...baseEvidence, status: "failed", error: err.message };
+        }
+    }
+}
+function batchSucceeded(entry, result) {
+    const allowedExitCodes = entry.success?.exitCodes ?? [0];
+    if (!allowedExitCodes.includes(result.exitCode))
+        return false;
+    for (const required of entry.success?.requiredOutput ?? []) {
+        if (!result.stdout.includes(required) && !result.stderr.includes(required)) {
+            return false;
+        }
+    }
+    return true;
+}
+function batchFailureMessage(entry, result) {
+    const allowedExitCodes = entry.success?.exitCodes ?? [0];
+    if (!allowedExitCodes.includes(result.exitCode)) {
+        const output = summarizeCommandOutput(result.stderr || result.stdout);
+        return output
+            ? `Batch failed with exit code ${result.exitCode}: ${output}`
+            : `Batch failed with exit code ${result.exitCode}.`;
+    }
+    for (const required of entry.success?.requiredOutput ?? []) {
+        if (!result.stdout.includes(required) && !result.stderr.includes(required)) {
+            return `Batch output did not contain required text '${required}'.`;
+        }
+    }
+    return "Batch did not satisfy success criteria.";
+}
+function summarizeCommandOutput(value) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= 300)
+        return normalized;
+    return `${normalized.slice(0, 297)}...`;
+}
+function summarizeBatch(command, displayCommand, attempts, fileUploads) {
+    const last = attempts[attempts.length - 1];
+    return {
+        command,
+        displayCommand,
+        status: last?.status ?? "failed",
+        fileUploads,
+        attempts,
+        stdout: last?.stdout ?? "",
+        stderr: last?.stderr ?? "",
+        exitCode: last?.exitCode,
+        tracePath: last?.tracePath,
+        errno: last?.errno,
+        stdoutTruncated: last?.stdoutTruncated,
+        stderrTruncated: last?.stderrTruncated
+    };
+}
+function fileRequired(name, specs) {
+    return specs.find((spec) => spec.name === name)?.required !== false;
+}
+function normalizeInputFileValue(value) {
+    if (typeof value === "string")
+        return { localPath: value, fileName: basename(value) };
+    if (isBatchInputFileValue(value))
+        return value;
+    throw new Error("Batch input file value must be a selected file object.");
+}
+function resolveRemotePath(spec, value, params, fileName) {
+    const template = value.remotePath || spec.remotePath;
+    if (!template?.trim())
+        throw new Error(`Batch input file '${spec.name}' needs a remote path.`);
+    const baseName = fileName.includes(".") ? fileName.slice(0, fileName.lastIndexOf(".")) : fileName;
+    const extension = fileName.includes(".") ? fileName.slice(fileName.lastIndexOf(".") + 1) : "";
+    const rendered = template.replace(/\$\{([A-Za-z0-9_.-]+)\}/g, (_match, name) => {
+        if (name === "fileName")
+            return fileName;
+        if (name === "baseName")
+            return baseName;
+        if (name === "extension")
+            return extension;
+        if (name === "inputName")
+            return spec.name;
+        const value = params[name] ?? process.env[name];
+        if (value === undefined || value === null)
+            throw new Error(`Batch input file '${spec.name}' remote path references unknown value '${name}'.`);
+        return String(value);
+    });
+    return /[\\/]$/.test(rendered) ? `${rendered}${fileName}` : rendered;
+}
+function resolveOutputRemotePath(spec, params, last) {
+    if (spec.remotePath?.trim()) {
+        return resolveTemplate(spec.remotePath, outputTemplateVars(spec, spec.remotePath, params));
+    }
+    if (!last)
+        return undefined;
+    const source = spec.source ?? "stderr";
+    const output = source === "stdout"
+        ? last.stdout
+        : source === "both"
+            ? `${last.stdout}\n${last.stderr}`
+            : last.stderr;
+    const pattern = spec.pathPattern?.trim() || "(\\/[^\\s'\"<>]+)";
+    const match = new RegExp(pattern, "m").exec(output);
+    return (match?.[1] ?? match?.[0])?.trim();
+}
+function outputTemplateVars(spec, remotePath, params) {
+    const fileName = remoteBaseName(remotePath) || `${spec.name}.out`;
+    const dot = fileName.lastIndexOf(".");
+    return {
+        ...params,
+        outputName: spec.name,
+        remotePath,
+        fileName,
+        baseName: dot > 0 ? fileName.slice(0, dot) : fileName,
+        extension: dot > 0 ? fileName.slice(dot + 1) : ""
+    };
+}
+function resolveTemplate(value, params) {
+    return value.replace(/\$\{([A-Za-z0-9_.-]+)\}/g, (_match, name) => {
+        const next = params[name] ?? process.env[name];
+        if (next === undefined || next === null)
+            throw new Error(`Batch output file template references unknown value '${name}'.`);
+        return String(next);
+    });
+}
+async function writeDownloadedFile(downloadDir, outputName, remotePath, content) {
+    const safeOutputName = sanitizePathPart(outputName || "output");
+    const safeFileName = sanitizePathPart(remoteBaseName(remotePath) || `${safeOutputName}.out`);
+    const localPath = join(downloadDir, safeOutputName, safeFileName);
+    await mkdir(dirname(localPath), { recursive: true });
+    await writeFile(localPath, content);
+    return localPath;
+}
+function remoteBaseName(remotePath) {
+    return remotePath.split(/[\\/]/).filter(Boolean).pop() ?? "";
+}
+function sanitizePathPart(value) {
+    return value.replace(/[^A-Za-z0-9_.-]/g, "_") || "file";
+}
+async function readInputFileContent(rootDir, value) {
+    if (value.contentBase64) {
+        const base64 = value.contentBase64.includes(",") ? value.contentBase64.slice(value.contentBase64.indexOf(",") + 1) : value.contentBase64;
+        return Buffer.from(base64, "base64");
+    }
+    if (!value.localPath)
+        throw new Error("Batch input file has no local file path.");
+    const path = isAbsolute(value.localPath) ? resolve(value.localPath) : resolve(rootDir, value.localPath);
+    const uploadsRoot = resolve(rootDir, "data", "batch-input-files");
+    const rel = relative(uploadsRoot, path);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error("Batch input file path must be under data/batch-input-files.");
+    }
+    return await readFile(path);
+}
+function extractBatchDiagnostics(stdout, stderr) {
+    const output = `${stdout}\n${stderr}`;
+    const tracePath = output.match(/FICHIER\s*:\s*(.+)/i)?.[1]?.trim();
+    const errno = output.match(/ERRNO\s*:\s*([^\s]+)/i)?.[1]?.trim();
+    return { tracePath, errno };
+}
+async function sleep(ms, signal) {
+    if (signal?.aborted)
+        throw cancellationError();
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(done, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(cancellationError());
+        };
+        function done() {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}