@livingdata/pipex 0.0.9 → 0.0.10

package/dist/cli/pipeline-runner.js

@@ -1,31 +1,17 @@
+import process from 'node:process';
+import { cpus } from 'node:os';
 import { cp, writeFile } from 'node:fs/promises';
+import { setTimeout } from 'node:timers/promises';
 import { createWriteStream } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { Workspace } from '../engine/index.js';
+import { ContainerCrashError, PipexError } from '../errors.js';
+import { buildGraph, topologicalLevels, subgraph, leafNodes } from './dag.js';
+import { evaluateCondition } from './condition.js';
 import { StateManager } from './state.js';
 import { dirSize } from './utils.js';
 /**
- * Orchestrates pipeline execution with dependency resolution and caching.
- *
- * ## Workflow
- *
- * 1. **Workspace Resolution**: Determines workspace ID from CLI flag, config, or filename
- * 2. **State Loading**: Loads cached fingerprints from state.json
- * 3. **Step Execution**: For each step:
- *    a. Computes fingerprint (image + cmd + env + input run IDs)
- *    b. Checks cache (fingerprint match + run exists)
- *    c. If cached: skips execution
- *    d. If not cached: resolves inputs, prepares staging, executes container
- *    e. On success: writes meta.json, commits run, saves state
- *    f. On failure: discards run, halts pipeline (unless allowFailure)
- * 4. **Completion**: Reports final pipeline status
- *
- * ## Runs
- *
- * Each step execution produces a **run** containing:
- * - `artifacts/` — files produced by the step
- * - `stdout.log` / `stderr.log` — captured container logs
- * - `meta.json` — structured execution metadata
+ * Orchestrates pipeline execution with DAG-based parallel execution and caching.
  */
 export class PipelineRunner {
     loader;
@@ -39,7 +25,7 @@ export class PipelineRunner {
         this.workdirRoot = workdirRoot;
     }
     async run(pipelineFilePath, options) {
-        const { workspace: workspaceName, force, dryRun } = options ?? {};
+        const { workspace: workspaceName, force, dryRun, target, concurrency } = options ?? {};
         const config = await this.loader.load(pipelineFilePath);
         const pipelineRoot = dirname(resolve(pipelineFilePath));
         const workspaceId = workspaceName ?? config.id;
@@ -59,36 +45,100 @@ export class PipelineRunner {
         await state.load();
         const stepRuns = new Map();
         let totalArtifactSize = 0;
-        this.reporter.state(workspace.id, 'PIPELINE_START', undefined, { pipelineName: config.name ?? config.id });
-        for (const step of config.steps) {
-            const stepRef = { id: step.id, displayName: step.name ?? step.id };
-            const inputRunIds = step.inputs
-                ?.map(i => stepRuns.get(i.step))
-                .filter((id) => id !== undefined);
-            const resolvedMounts = step.mounts?.map(m => ({
-                hostPath: resolve(pipelineRoot, m.host),
-                containerPath: m.container
-            }));
-            const currentFingerprint = StateManager.fingerprint({
-                image: step.image,
-                cmd: step.cmd,
-                env: step.env,
-                inputRunIds,
-                mounts: resolvedMounts
+        // Build DAG and determine execution scope
+        const graph = buildGraph(config.steps);
+        const targets = target ?? leafNodes(graph);
+        const activeSteps = subgraph(graph, targets);
+        this.reporter.emit({
+            event: 'PIPELINE_START',
+            workspaceId: workspace.id,
+            pipelineName: config.name ?? config.id,
+            steps: config.steps
+                .filter(s => activeSteps.has(s.id))
+                .map(s => ({ id: s.id, displayName: s.name ?? s.id }))
+        });
+        const levels = topologicalLevels(graph)
+            .map(level => level.filter(id => activeSteps.has(id)))
+            .filter(level => level.length > 0);
+        const stepMap = new Map(config.steps.map(s => [s.id, s]));
+        const failed = new Set();
+        const skipped = new Set();
+        const maxConcurrency = concurrency ?? cpus().length;
+        for (const level of levels) {
+            const tasks = level.map(stepId => async () => {
+                const step = stepMap.get(stepId);
+                const stepRef = { id: step.id, displayName: step.name ?? step.id };
+                // Check if blocked by a failed/skipped required dependency
+                if (this.isDependencyBlocked(step, failed, skipped)) {
+                    skipped.add(step.id);
+                    this.reporter.emit({ event: 'STEP_SKIPPED', workspaceId: workspace.id, step: stepRef, reason: 'dependency' });
+                    return 0;
+                }
+                // Evaluate condition
+                if (step.if) {
+                    const conditionMet = await evaluateCondition(step.if, { env: process.env });
+                    if (!conditionMet) {
+                        skipped.add(step.id);
+                        this.reporter.emit({ event: 'STEP_SKIPPED', workspaceId: workspace.id, step: stepRef, reason: 'condition' });
+                        return 0;
+                    }
+                }
+                // Compute fingerprint
+                const inputRunIds = step.inputs
+                    ?.map(i => stepRuns.get(i.step))
+                    .filter((id) => id !== undefined);
+                const resolvedMounts = step.mounts?.map(m => ({
+                    hostPath: resolve(pipelineRoot, m.host),
+                    containerPath: m.container
+                }));
+                const currentFingerprint = StateManager.fingerprint({
+                    image: step.image,
+                    cmd: step.cmd,
+                    env: step.env,
+                    inputRunIds,
+                    mounts: resolvedMounts
+                });
+                // Cache check
+                const skipCache = force === true || (Array.isArray(force) && force.includes(step.id));
+                if (!skipCache && await this.tryUseCache({ workspace, state, step, stepRef, currentFingerprint, stepRuns })) {
+                    return 0;
+                }
+                // Dry run
+                if (dryRun) {
+                    this.reporter.emit({ event: 'STEP_WOULD_RUN', workspaceId: workspace.id, step: stepRef });
+                    return 0;
+                }
+                // Execute
+                this.reporter.emit({ event: 'STEP_STARTING', workspaceId: workspace.id, step: stepRef });
+                return this.executeStep({ workspace, state, step, stepRef, stepRuns, currentFingerprint, resolvedMounts, pipelineRoot });
             });
-            const skipCache = force === true || (Array.isArray(force) && force.includes(step.id));
-            if (!skipCache && await this.tryUseCache({ workspace, state, step, stepRef, currentFingerprint, stepRuns })) {
-                continue;
-            }
-            if (dryRun) {
-                this.reporter.state(workspace.id, 'STEP_WOULD_RUN', stepRef);
-                continue;
+            const results = await withConcurrency(tasks, maxConcurrency);
+            // Collect results
+            for (const [i, result] of results.entries()) {
+                const stepId = level[i];
+                if (result.status === 'fulfilled') {
+                    totalArtifactSize += result.value;
+                }
+                else if (!failed.has(stepId)) {
+                    // Step threw an error (ContainerCrashError if not allowFailure)
+                    failed.add(stepId);
+                }
             }
-            this.reporter.state(workspace.id, 'STEP_STARTING', stepRef);
-            const stepArtifactSize = await this.executeStep({ workspace, state, step, stepRef, stepRuns, currentFingerprint, resolvedMounts, pipelineRoot });
-            totalArtifactSize += stepArtifactSize;
+            await state.save();
+        }
+        if (failed.size > 0) {
+            this.reporter.emit({ event: 'PIPELINE_FAILED', workspaceId: workspace.id });
+            // Re-throw the first failure to signal pipeline failure to the CLI
+            const firstFailedId = [...failed][0];
+            throw new ContainerCrashError(firstFailedId, 1);
         }
-        this.reporter.state(workspace.id, 'PIPELINE_FINISHED', undefined, { totalArtifactSize });
+        this.reporter.emit({ event: 'PIPELINE_FINISHED', workspaceId: workspace.id, totalArtifactSize });
+    }
+    isDependencyBlocked(step, failed, skippedSteps) {
+        if (!step.inputs) {
+            return false;
+        }
+        return step.inputs.some(input => !input.optional && (failed.has(input.step) || skippedSteps.has(input.step)));
     }
     async executeStep({ workspace, state, step, stepRef, stepRuns, currentFingerprint, resolvedMounts, pipelineRoot }) {
         const runId = workspace.generateRunId();
@@ -103,30 +153,46 @@ export class PipelineRunner {
         const stdoutLog = createWriteStream(join(stagingPath, 'stdout.log'));
         const stderrLog = createWriteStream(join(stagingPath, 'stderr.log'));
         try {
-            const result = await this.runtime.run(workspace, {
-                name: `pipex-${workspace.id}-${step.id}-${Date.now()}`,
-                image: step.image,
-                cmd: step.cmd,
-                env: step.env,
-                inputs,
-                output,
-                caches,
-                mounts,
-                sources: step.sources?.map(m => ({
-                    hostPath: resolve(pipelineRoot, m.host),
-                    containerPath: m.container
-                })),
-                network: step.allowNetwork ? 'bridge' : 'none',
-                timeoutSec: step.timeoutSec
-            }, ({ stream, line }) => {
-                if (stream === 'stdout') {
-                    stdoutLog.write(line + '\n');
+            const maxRetries = step.retries ?? 0;
+            const retryDelay = step.retryDelayMs ?? 5000;
+            let result;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    result = await this.runtime.run(workspace, {
+                        name: `pipex-${workspace.id}-${step.id}-${Date.now()}`,
+                        image: step.image,
+                        cmd: step.cmd,
+                        env: step.env,
+                        inputs,
+                        output,
+                        caches,
+                        mounts,
+                        sources: step.sources?.map(m => ({
+                            hostPath: resolve(pipelineRoot, m.host),
+                            containerPath: m.container
+                        })),
+                        network: step.allowNetwork ? 'bridge' : 'none',
+                        timeoutSec: step.timeoutSec
+                    }, ({ stream, line }) => {
+                        if (stream === 'stdout') {
+                            stdoutLog.write(line + '\n');
+                        }
+                        else {
+                            stderrLog.write(line + '\n');
+                        }
+                        this.reporter.log(workspace.id, stepRef, stream, line);
+                    });
+                    break;
                 }
-                else {
-                    stderrLog.write(line + '\n');
+                catch (error) {
+                    if (error instanceof PipexError && error.transient && attempt < maxRetries) {
+                        this.reporter.emit({ event: 'STEP_RETRYING', workspaceId: workspace.id, step: stepRef, attempt: attempt + 1, maxRetries });
+                        await setTimeout(retryDelay);
+                        continue;
+                    }
+                    throw error;
                 }
-                this.reporter.log(workspace.id, stepRef, stream, line);
-            });
+            }
             this.reporter.result(workspace.id, stepRef, result);
             await closeStream(stdoutLog);
             await closeStream(stderrLog);
@@ -136,16 +202,14 @@ export class PipelineRunner {
                 await workspace.linkRun(step.id, runId);
                 stepRuns.set(step.id, runId);
                 state.setStep(step.id, runId, currentFingerprint);
-                await state.save();
                 const durationMs = result.finishedAt.getTime() - result.startedAt.getTime();
                 const artifactSize = await dirSize(workspace.runArtifactsPath(runId));
-                this.reporter.state(workspace.id, 'STEP_FINISHED', stepRef, { runId, durationMs, artifactSize });
+                this.reporter.emit({ event: 'STEP_FINISHED', workspaceId: workspace.id, step: stepRef, runId, durationMs, artifactSize });
                 return artifactSize;
             }
             await workspace.discardRun(runId);
-            this.reporter.state(workspace.id, 'STEP_FAILED', stepRef, { exitCode: result.exitCode });
-            this.reporter.state(workspace.id, 'PIPELINE_FAILED');
-            throw new Error(`Step ${step.id} failed with exit code ${result.exitCode}`);
+            this.reporter.emit({ event: 'STEP_FAILED', workspaceId: workspace.id, step: stepRef, exitCode: result.exitCode });
+            throw new ContainerCrashError(step.id, result.exitCode);
         }
         catch (error) {
             await closeStream(stdoutLog);
@@ -186,7 +250,7 @@ export class PipelineRunner {
                 if (runs.includes(cached.runId)) {
                     stepRuns.set(step.id, cached.runId);
                     await workspace.linkRun(step.id, cached.runId);
-                    this.reporter.state(workspace.id, 'STEP_SKIPPED', stepRef, { runId: cached.runId, reason: 'cached' });
+                    this.reporter.emit({ event: 'STEP_SKIPPED', workspaceId: workspace.id, step: stepRef, runId: cached.runId, reason: 'cached' });
                     return true;
                 }
             }
@@ -203,7 +267,12 @@ export class PipelineRunner {
         for (const input of step.inputs) {
             const inputRunId = stepRuns.get(input.step);
             if (!inputRunId) {
-                throw new Error(`Step ${step.id}: input step '${input.step}' not found or not yet executed`);
+                if (input.optional) {
+                    continue;
+                }
+                // Non-optional input without a run — this shouldn't happen in DAG mode
+                // but keep the continue for safety (the step may still work with bind mounts)
+                continue;
             }
             if (input.copyToOutput) {
                 await cp(workspace.runArtifactsPath(inputRunId), stagingArtifactsPath, { recursive: true });
@@ -244,6 +313,23 @@ export class PipelineRunner {
         return { inputs, output, caches, mounts };
     }
 }
+async function withConcurrency(tasks, limit) {
+    const results = Array.from({ length: tasks.length });
+    let next = 0;
+    async function worker() {
+        while (next < tasks.length) {
+            const i = next++;
+            try {
+                results[i] = { status: 'fulfilled', value: await tasks[i]() };
+            }
+            catch (error) {
+                results[i] = { status: 'rejected', reason: error };
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, async () => worker()));
+    return results;
+}
 async function closeStream(stream) {
     if (stream.destroyed) {
         return;

package/dist/cli/reporter.js

@@ -1,16 +1,12 @@
 import pino from 'pino';
-import chalk from 'chalk';
-import ora from 'ora';
-import { formatDuration, formatSize } from './utils.js';
 /**
  * Reporter that outputs structured JSON logs via pino.
  * Suitable for CI/CD environments and log aggregation.
  */
 export class ConsoleReporter {
     logger = pino({ level: 'info' });
-    state(workspaceId, event, step, meta) {
-        const stepName = step?.displayName === step?.id ? undefined : step?.displayName;
-        this.logger.info({ workspaceId, event, stepId: step?.id, stepName, ...meta });
+    emit(event) {
+        this.logger.info(event);
     }
     log(workspaceId, step, stream, line) {
         this.logger.info({ workspaceId, stepId: step.id, stream, line });
@@ -19,155 +15,3 @@ export class ConsoleReporter {
         this.logger.info({ workspaceId, stepId: step.id, result });
     }
 }
-/**
- * Reporter with interactive terminal UI using spinners and colors.
- * Suitable for local development and manual execution.
- */
-export class InteractiveReporter {
-    static get maxStderrLines() {
-        return 20;
-    }
-    verbose;
-    spinner;
-    stepSpinners = new Map();
-    stderrBuffers = new Map();
-    constructor(options) {
-        this.verbose = options?.verbose ?? false;
-    }
-    state(workspaceId, event, step, meta) {
-        switch (event) {
-            case 'PIPELINE_START': {
-                const displayName = meta?.pipelineName ?? workspaceId;
-                console.log(chalk.bold(`\n▶ Pipeline: ${chalk.cyan(displayName)}\n`));
-                break;
-            }
-            case 'STEP_STARTING': {
-                if (step) {
-                    const spinner = ora({ text: step.displayName, prefixText: '  ' }).start();
-                    this.stepSpinners.set(step.id, spinner);
-                }
-                break;
-            }
-            case 'STEP_SKIPPED': {
-                if (step) {
-                    const spinner = this.stepSpinners.get(step.id);
-                    if (spinner) {
-                        spinner.stopAndPersist({ symbol: chalk.gray('⊙'), text: chalk.gray(`${step.displayName} (cached)`) });
-                        this.stepSpinners.delete(step.id);
-                    }
-                    else {
-                        console.log(`  ${chalk.gray('⊙')} ${chalk.gray(`${step.displayName} (cached)`)}`);
-                    }
-                }
-                break;
-            }
-            case 'STEP_FINISHED': {
-                if (step) {
-                    this.handleStepFinished(step, meta);
-                }
-                break;
-            }
-            case 'STEP_FAILED': {
-                if (step) {
-                    this.handleStepFailed(step, meta);
-                }
-                break;
-            }
-            case 'STEP_WOULD_RUN': {
-                if (step) {
-                    this.handleStepWouldRun(step);
-                }
-                break;
-            }
-            case 'PIPELINE_FINISHED': {
-                this.handlePipelineFinished(meta);
-                break;
-            }
-            case 'PIPELINE_FAILED': {
-                console.log(chalk.bold.red('\n✗ Pipeline failed\n'));
-                break;
-            }
-        }
-    }
-    log(_workspaceId, step, stream, line) {
-        if (this.verbose) {
-            const spinner = this.stepSpinners.get(step.id);
-            const prefix = chalk.gray(`  [${step.id}]`);
-            if (spinner) {
-                spinner.clear();
-                console.log(`${prefix} ${line}`);
-                spinner.render();
-            }
-            else {
-                console.log(`${prefix} ${line}`);
-            }
-        }
-        if (stream === 'stderr') {
-            let buffer = this.stderrBuffers.get(step.id);
-            if (!buffer) {
-                buffer = [];
-                this.stderrBuffers.set(step.id, buffer);
-            }
-            buffer.push(line);
-            if (buffer.length > InteractiveReporter.maxStderrLines) {
-                buffer.shift();
-            }
-        }
-    }
-    result(_workspaceId, _step, _result) {
-        // Results shown via state updates
-    }
-    handleStepFinished(step, meta) {
-        const spinner = this.stepSpinners.get(step.id);
-        if (spinner) {
-            const details = [];
-            if (typeof meta?.durationMs === 'number') {
-                details.push(formatDuration(meta.durationMs));
-            }
-            if (typeof meta?.artifactSize === 'number' && meta.artifactSize > 0) {
-                details.push(formatSize(meta.artifactSize));
-            }
-            const suffix = details.length > 0 ? ` (${details.join(', ')})` : '';
-            spinner.stopAndPersist({ symbol: chalk.green('✓'), text: chalk.green(`${step.displayName}${suffix}`) });
-            this.stepSpinners.delete(step.id);
-        }
-        this.stderrBuffers.delete(step.id);
-    }
-    handleStepWouldRun(step) {
-        const spinner = this.stepSpinners.get(step.id);
-        if (spinner) {
-            spinner.stopAndPersist({ symbol: chalk.yellow('○'), text: chalk.yellow(`${step.displayName} (would run)`) });
-            this.stepSpinners.delete(step.id);
-        }
-        else {
-            console.log(`  ${chalk.yellow('○')} ${chalk.yellow(`${step.displayName} (would run)`)}`);
-        }
-    }
-    handlePipelineFinished(meta) {
-        const parts = ['Pipeline completed'];
-        if (typeof meta?.totalArtifactSize === 'number' && meta.totalArtifactSize > 0) {
-            parts.push(`(${formatSize(meta.totalArtifactSize)})`);
-        }
-        console.log(chalk.bold.green(`\n✓ ${parts.join(' ')}\n`));
-    }
-    handleStepFailed(step, meta) {
-        const spinner = this.stepSpinners.get(step.id);
-        const exitCode = meta?.exitCode;
-        if (spinner) {
-            const exitInfo = exitCode === undefined ? '' : ` (exit ${exitCode})`;
-            spinner.stopAndPersist({
-                symbol: chalk.red('✗'),
-                text: chalk.red(`${step.displayName}${exitInfo}`)
-            });
-            this.stepSpinners.delete(step.id);
-        }
-        const stderr = this.stderrBuffers.get(step.id);
-        if (stderr && stderr.length > 0) {
-            console.log(chalk.red('  ── stderr ──'));
-            for (const line of stderr) {
-                console.log(chalk.red(`  ${line}`));
-            }
-        }
-        this.stderrBuffers.delete(step.id);
-    }
-}

package/dist/cli/state.js

@@ -99,4 +99,12 @@ export class StateManager {
     setStep(stepId, runId, fingerprint) {
         this.state.steps[stepId] = { runId, fingerprint };
     }
+    /**
+     * Removes a step's cached state.
+     * @param stepId - Step identifier
+     */
+    removeStep(stepId) {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete this.state.steps[stepId];
+    }
 }

package/dist/cli/step-loader.js

@@ -0,0 +1,25 @@
+import { readFile } from 'node:fs/promises';
+import { ValidationError } from '../errors.js';
+import { parsePipelineFile } from './pipeline-loader.js';
+import { resolveStep, validateStep } from './step-resolver.js';
+/**
+ * Loads and resolves a single step definition from a file.
+ */
+export async function loadStepFile(filePath, stepIdOverride) {
+    const content = await readFile(filePath, 'utf8');
+    const raw = parsePipelineFile(content, filePath);
+    if (!raw || typeof raw !== 'object') {
+        throw new ValidationError('Step file must contain an object');
+    }
+    // If no id/name provided, require --step override
+    if (!('id' in raw && raw.id) && !('name' in raw && raw.name) && !stepIdOverride) {
+        throw new ValidationError('Step file must have "id" or "name", or use --step to set an ID');
+    }
+    // Apply step ID override
+    if (stepIdOverride) {
+        raw.id = stepIdOverride;
+    }
+    const step = resolveStep(raw);
+    validateStep(step);
+    return step;
+}

package/dist/cli/step-resolver.js

@@ -0,0 +1,111 @@
+import { ValidationError } from '../errors.js';
+import { getKit } from '../kits/index.js';
+import { isKitStep } from '../types.js';
+import { slugify, mergeEnv, mergeCaches, mergeMounts } from './pipeline-loader.js';
+/**
+ * Resolves a step definition into a fully resolved Step.
+ * Kit steps (`uses`) are expanded into image + cmd.
+ */
+export function resolveStep(step) {
+    if (!step.id && !step.name) {
+        throw new ValidationError('Invalid step: at least one of "id" or "name" must be defined');
+    }
+    const id = step.id ?? slugify(step.name);
+    const { name } = step;
+    if (!isKitStep(step)) {
+        return { ...step, id, name };
+    }
+    return resolveKitStep(step, id, name);
+}
+function resolveKitStep(step, id, name) {
+    const kit = getKit(step.uses);
+    const kitOutput = kit.resolve(step.with ?? {});
+    return {
+        id,
+        name,
+        image: kitOutput.image,
+        cmd: kitOutput.cmd,
+        env: mergeEnv(kitOutput.env, step.env),
+        inputs: step.inputs,
+        outputPath: step.outputPath,
+        caches: mergeCaches(kitOutput.caches, step.caches),
+        mounts: mergeMounts(kitOutput.mounts, step.mounts),
+        sources: mergeMounts(kitOutput.sources, step.sources),
+        timeoutSec: step.timeoutSec,
+        allowFailure: step.allowFailure,
+        allowNetwork: step.allowNetwork ?? kitOutput.allowNetwork,
+        retries: step.retries,
+        retryDelayMs: step.retryDelayMs,
+        if: step.if
+    };
+}
+/**
+ * Validates a resolved step for correctness and security.
+ */
+export function validateStep(step) {
+    validateIdentifier(step.id, 'step id');
+    if (!step.image || typeof step.image !== 'string') {
+        throw new ValidationError(`Invalid step ${step.id}: image is required`);
+    }
+    if (!Array.isArray(step.cmd) || step.cmd.length === 0) {
+        throw new ValidationError(`Invalid step ${step.id}: cmd must be a non-empty array`);
+    }
+    if (step.inputs) {
+        for (const input of step.inputs) {
+            validateIdentifier(input.step, `input step name in step ${step.id}`);
+        }
+    }
+    if (step.mounts) {
+        validateMounts(step.id, step.mounts);
+    }
+    if (step.sources) {
+        validateMounts(step.id, step.sources);
+    }
+    if (step.caches) {
+        validateCaches(step.id, step.caches);
+    }
+}
+function validateIdentifier(id, context) {
+    if (!/^[\w-]+$/.test(id)) {
+        throw new ValidationError(`Invalid ${context}: '${id}' must contain only alphanumeric characters, underscore, and hyphen`);
+    }
+    if (id.includes('..')) {
+        throw new ValidationError(`Invalid ${context}: '${id}' cannot contain '..'`);
+    }
+}
+function validateMounts(stepId, mounts) {
+    for (const mount of mounts) {
+        if (!mount.host || typeof mount.host !== 'string') {
+            throw new ValidationError(`Step ${stepId}: mount.host is required and must be a string`);
+        }
+        if (mount.host.startsWith('/')) {
+            throw new ValidationError(`Step ${stepId}: mount.host '${mount.host}' must be a relative path`);
+        }
+        if (mount.host.includes('..')) {
+            throw new ValidationError(`Step ${stepId}: mount.host '${mount.host}' must not contain '..'`);
+        }
+        if (!mount.container || typeof mount.container !== 'string') {
+            throw new ValidationError(`Step ${stepId}: mount.container is required and must be a string`);
+        }
+        if (!mount.container.startsWith('/')) {
+            throw new ValidationError(`Step ${stepId}: mount.container '${mount.container}' must be an absolute path`);
+        }
+        if (mount.container.includes('..')) {
+            throw new ValidationError(`Step ${stepId}: mount.container '${mount.container}' must not contain '..'`);
+        }
+    }
+}
+function validateCaches(stepId, caches) {
+    for (const cache of caches) {
+        if (!cache.name || typeof cache.name !== 'string') {
+            throw new ValidationError(`Step ${stepId}: cache.name is required and must be a string`);
+        }
+        validateIdentifier(cache.name, `cache name in step ${stepId}`);
+        if (!cache.path || typeof cache.path !== 'string') {
+            throw new ValidationError(`Step ${stepId}: cache.path is required and must be a string`);
+        }
+        if (!cache.path.startsWith('/')) {
+            throw new ValidationError(`Step ${stepId}: cache.path '${cache.path}' must be an absolute path`);
+        }
+    }
+}