adfinem 0.0.0 → 0.1.0

package/src/adapters/unix/batch-runner.ts

@@ -0,0 +1,456 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import type { BatchCatalogEntry, BatchFileDownloadEvidence, BatchFileUploadEvidence, BatchInputFileSpec, BatchInputFileValue, BatchOutputFileSpec } from "../../dsl/types.js";
+import { buildBatchCommandDetails } from "./batch-catalog.js";
+import { hasBatchInputFilePayload, isBatchInputFileValue } from "./batch-input-files.js";
+import { SshClient } from "./ssh-client.js";
+import { cancellationError, isCancellationError } from "../../engine/step-result.js";
+
+export interface BatchAttemptResult {
+  attempt: number;
+  startedAt: string;
+  endedAt: string;
+  command: string;
+  displayCommand: string;
+  stdout: string;
+  stderr: string;
+  exitCode?: number;
+  tracePath?: string;
+  errno?: string;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
+  status: "passed" | "failed";
+  error?: string;
+}
+
+export interface BatchRunOptions {
+  attempts?: number;
+  delayMs?: number;
+  signal?: AbortSignal;
+  downloadDir?: string;
+}
+
+export interface BatchRunResult {
+  command: string;
+  displayCommand: string;
+  status: "passed" | "failed";
+  fileUploads?: BatchFileUploadEvidence[];
+  fileDownloads?: BatchFileDownloadEvidence[];
+  attempts: BatchAttemptResult[];
+  stdout: string;
+  stderr: string;
+  exitCode?: number;
+  tracePath?: string;
+  errno?: string;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
+}
+
+export class BatchRunner {
+  constructor(private readonly ssh: SshClient, private readonly rootDir = process.cwd()) {}
+
+  async run(entry: BatchCatalogEntry, params: Record<string, unknown>, options: BatchRunOptions = {}): Promise<BatchRunResult> {
+    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: BatchAttemptResult[] = [];
+
+    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: BatchAttemptResult = {
+          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);
+  }
+
+  private async uploadInputFiles(
+    entry: BatchCatalogEntry,
+    params: Record<string, unknown>,
+    options: BatchRunOptions
+  ): Promise<{ params: Record<string, unknown>; appendedArgs: string[]; fileUploads: BatchFileUploadEvidence[] | undefined }> {
+    const inputFiles = entry.inputFiles ?? [];
+    if (inputFiles.length === 0) return { params, appendedArgs: [], fileUploads: undefined };
+
+    const commandParams = { ...params };
+    const appendedArgs: string[] = [];
+    const fileUploads: BatchFileUploadEvidence[] = [];
+    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: BatchFileUploadEvidence = {
+        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 };
+  }
+
+  private async withOutputFiles(
+    entry: BatchCatalogEntry,
+    params: Record<string, unknown>,
+    summary: BatchRunResult,
+    options: BatchRunOptions
+  ): Promise<BatchRunResult> {
+    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: BatchFileDownloadEvidence[] = [];
+
+    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 };
+  }
+
+  private async retrieveOutputFile(
+    entry: BatchCatalogEntry,
+    spec: BatchOutputFileSpec,
+    params: Record<string, unknown>,
+    last: BatchAttemptResult | undefined,
+    timeoutMs: number,
+    options: BatchRunOptions
+  ): Promise<BatchFileDownloadEvidence> {
+    const source = spec.source ?? (spec.remotePath ? "explicit" : "stderr");
+    const baseEvidence: BatchFileDownloadEvidence = { 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: string | undefined;
+      let downloadRemotePath = remotePath;
+      let decryptExitCode: number | undefined;
+      let decryptStdout: string | undefined;
+      let decryptStderr: string | undefined;
+      let decryptedRemotePath: string | undefined;
+
+      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: BatchCatalogEntry, result: { stdout: string; stderr: string; exitCode: number }): boolean {
+    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: BatchCatalogEntry, result: { stdout: string; stderr: string; exitCode: number }): string {
+  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: string): string {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized.length <= 300) return normalized;
+  return `${normalized.slice(0, 297)}...`;
+}
+
+function summarizeBatch(command: string, displayCommand: string, attempts: BatchAttemptResult[], fileUploads?: BatchFileUploadEvidence[]): BatchRunResult {
+  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: string, specs: BatchOutputFileSpec[]): boolean {
+  return specs.find((spec) => spec.name === name)?.required !== false;
+}
+
+function normalizeInputFileValue(value: unknown): BatchInputFileValue {
+  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: BatchInputFileSpec,
+  value: BatchInputFileValue,
+  params: Record<string, unknown>,
+  fileName: string
+): string {
+  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: string) => {
+    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: BatchOutputFileSpec,
+  params: Record<string, unknown>,
+  last: BatchAttemptResult | undefined
+): string | undefined {
+  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: BatchOutputFileSpec, remotePath: string, params: Record<string, unknown>): Record<string, unknown> {
+  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: string, params: Record<string, unknown>): string {
+  return value.replace(/\$\{([A-Za-z0-9_.-]+)\}/g, (_match, name: string) => {
+    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: string, outputName: string, remotePath: string, content: Buffer): Promise<string> {
+  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: string): string {
+  return remotePath.split(/[\\/]/).filter(Boolean).pop() ?? "";
+}
+
+function sanitizePathPart(value: string): string {
+  return value.replace(/[^A-Za-z0-9_.-]/g, "_") || "file";
+}
+
+async function readInputFileContent(rootDir: string, value: BatchInputFileValue): Promise<Buffer> {
+  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: string, stderr: string): { tracePath?: string; errno?: string } {
+  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: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) throw cancellationError();
+  await new Promise<void>((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 });
+  });
+}

package/src/adapters/unix/ssh-client.ts

@@ -0,0 +1,248 @@
+import { readFile } from "node:fs/promises";
+import { posix as posixPath } from "node:path";
+import { Client, type SFTPWrapper } from "ssh2";
+import type { EnvironmentConfig } from "../../config/environments.js";
+import { cancellationError } from "../../engine/step-result.js";
+
+export interface SshExecutionResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
+}
+
+const MAX_CAPTURE_BYTES = 5 * 1024 * 1024;
+
+export class SshClient {
+  constructor(private readonly env: EnvironmentConfig) {}
+
+  async execute(hostRef: string, command: string, timeoutMs: number, signal?: AbortSignal): Promise<SshExecutionResult> {
+    const host = this.hostConfig(hostRef);
+    const privateKey = await this.privateKey(host);
+    if (signal?.aborted) throw cancellationError();
+
+    const execCommand = buildSshExecCommand(host, command);
+
+    return await new Promise<SshExecutionResult>((resolve, reject) => {
+      const client = new Client();
+      let timer: NodeJS.Timeout | undefined;
+      let settled = false;
+      const abort = () => finish(() => reject(cancellationError()));
+
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        client.end();
+        fn();
+      };
+
+      signal?.addEventListener("abort", abort, { once: true });
+
+      client.on("ready", () => {
+        timer = setTimeout(() => {
+          finish(() => reject(new Error(`SSH command timed out after ${timeoutMs}ms.`)));
+        }, timeoutMs);
+
+        client.exec(execCommand, (err, stream) => {
+          if (err) {
+            finish(() => reject(err));
+            return;
+          }
+
+          let stdout = "";
+          let stderr = "";
+          let stdoutTruncated = false;
+          let stderrTruncated = false;
+          let exitCode = 0;
+          stream.on("close", (code: number | null) => {
+            exitCode = code ?? 0;
+            finish(() => resolve({ stdout, stderr, exitCode, stdoutTruncated, stderrTruncated }));
+          });
+          stream.on("data", (data: Buffer) => {
+            const result = appendLimited(stdout, data);
+            stdout = result.value;
+            stdoutTruncated = stdoutTruncated || result.truncated;
+          });
+          stream.stderr.on("data", (data: Buffer) => {
+            const result = appendLimited(stderr, data);
+            stderr = result.value;
+            stderrTruncated = stderrTruncated || result.truncated;
+          });
+        });
+      });
+
+      client.on("error", (error) => finish(() => reject(error)));
+      client.connect({
+        host: host.host,
+        username: host.username,
+        password: host.password,
+        privateKey,
+        readyTimeout: Math.min(timeoutMs, 30_000)
+      });
+    });
+  }
+
+  async uploadFile(hostRef: string, remotePath: string, content: Buffer, timeoutMs: number, signal?: AbortSignal): Promise<void> {
+    const host = this.hostConfig(hostRef);
+    const privateKey = await this.privateKey(host);
+    if (signal?.aborted) throw cancellationError();
+
+    await new Promise<void>((resolve, reject) => {
+      const client = new Client();
+      let timer: NodeJS.Timeout | undefined;
+      let settled = false;
+      const abort = () => finish(() => reject(cancellationError()));
+
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        client.end();
+        fn();
+      };
+
+      signal?.addEventListener("abort", abort, { once: true });
+
+      client.on("ready", () => {
+        timer = setTimeout(() => {
+          finish(() => reject(new Error(`SFTP upload timed out after ${timeoutMs}ms.`)));
+        }, timeoutMs);
+
+        client.sftp((err, sftp) => {
+          if (err) {
+            finish(() => reject(err));
+            return;
+          }
+          void mkdirpSftp(sftp, posixPath.dirname(remotePath))
+            .then(() => new Promise<void>((writeResolve, writeReject) => {
+              sftp.writeFile(remotePath, content, (writeError) => {
+                if (writeError) writeReject(writeError);
+                else writeResolve();
+              });
+            }))
+            .then(() => finish(resolve))
+            .catch((uploadError) => finish(() => reject(uploadError)));
+        });
+      });
+
+      client.on("error", (error) => finish(() => reject(error)));
+      client.connect({
+        host: host.host,
+        username: host.username,
+        password: host.password,
+        privateKey,
+        readyTimeout: Math.min(timeoutMs, 30_000)
+      });
+    });
+  }
+
+  async downloadFile(hostRef: string, remotePath: string, timeoutMs: number, signal?: AbortSignal): Promise<Buffer> {
+    const host = this.hostConfig(hostRef);
+    const privateKey = await this.privateKey(host);
+    if (signal?.aborted) throw cancellationError();
+
+    return await new Promise<Buffer>((resolve, reject) => {
+      const client = new Client();
+      let timer: NodeJS.Timeout | undefined;
+      let settled = false;
+      const abort = () => finish(() => reject(cancellationError()));
+
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        client.end();
+        fn();
+      };
+
+      signal?.addEventListener("abort", abort, { once: true });
+
+      client.on("ready", () => {
+        timer = setTimeout(() => {
+          finish(() => reject(new Error(`SFTP download timed out after ${timeoutMs}ms.`)));
+        }, timeoutMs);
+
+        client.sftp((err, sftp) => {
+          if (err) {
+            finish(() => reject(err));
+            return;
+          }
+          sftp.readFile(remotePath, (readError, content) => {
+            if (readError) finish(() => reject(readError));
+            else finish(() => resolve(content));
+          });
+        });
+      });
+
+      client.on("error", (error) => finish(() => reject(error)));
+      client.connect({
+        host: host.host,
+        username: host.username,
+        password: host.password,
+        privateKey,
+        readyTimeout: Math.min(timeoutMs, 30_000)
+      });
+    });
+  }
+
+  private hostConfig(hostRef: string): NonNullable<EnvironmentConfig["sshHosts"][string]> {
+    const host = this.env.sshHosts[hostRef];
+    if (!host) throw new Error(`Unknown SSH hostRef '${hostRef}'.`);
+    if (!host.host || !host.username) throw new Error(`SSH host '${hostRef}' requires host and username.`);
+    return host;
+  }
+
+  private async privateKey(host: NonNullable<EnvironmentConfig["sshHosts"][string]>): Promise<string | undefined> {
+    return host.privateKeyPath ? await readFile(host.privateKeyPath, "utf8") : undefined;
+  }
+}
+
+export function buildSshExecCommand(
+  host: { shell?: string; loginShell?: boolean },
+  command: string
+): string {
+  if (!host.loginShell) return command;
+  const shell = host.shell?.trim() || "bash";
+  return `${shellQuote(shell)} -lc ${shellQuote(command)}`;
+}
+
+function appendLimited(current: string, chunk: Buffer): { value: string; truncated: boolean } {
+  const next = current + chunk.toString("utf8");
+  const nextBytes = Buffer.byteLength(next, "utf8");
+  if (nextBytes <= MAX_CAPTURE_BYTES) return { value: next, truncated: false };
+  const buffer = Buffer.from(next, "utf8");
+  const tail = buffer.subarray(buffer.length - MAX_CAPTURE_BYTES);
+  return { value: tail.toString("utf8"), truncated: true };
+}
+
+async function mkdirpSftp(sftp: SFTPWrapper, directory: string): Promise<void> {
+  if (!sftp || !directory || directory === "." || directory === "/") return;
+  const absolute = directory.startsWith("/");
+  const parts = directory.split("/").filter(Boolean);
+  let current = absolute ? "/" : "";
+  for (const part of parts) {
+    current = current === "/" ? `/${part}` : current ? `${current}/${part}` : part;
+    if (await sftpPathExists(sftp, current)) continue;
+    await new Promise<void>((resolve, reject) => {
+      sftp.mkdir(current, (error) => {
+        if (error && (error as NodeJS.ErrnoException).code !== "EEXIST") reject(error);
+        else resolve();
+      });
+    });
+  }
+}
+
+async function sftpPathExists(sftp: SFTPWrapper, path: string): Promise<boolean> {
+  return await new Promise<boolean>((resolve) => {
+    sftp.stat(path, (error) => resolve(!error));
+  });
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}