@livingdata/pipex 0.0.8 → 0.0.10

package/dist/core/__tests__/pipeline-loader.js

@@ -0,0 +1,267 @@
+import test from 'ava';
+import { CyclicDependencyError, ValidationError } from '../../errors.js';
+import { PipelineLoader, slugify, parsePipelineFile, mergeEnv, mergeCaches, mergeMounts } from '../pipeline-loader.js';
+// ---------------------------------------------------------------------------
+// slugify
+// ---------------------------------------------------------------------------
+test('slugify converts accented characters', t => {
+    t.is(slugify('Étape numéro un'), 'etape-numero-un');
+});
+test('slugify replaces spaces with hyphens', t => {
+    t.is(slugify('hello world'), 'hello-world');
+});
+test('slugify replaces special characters', t => {
+    t.is(slugify('build@v2!'), 'build-v2');
+    t.is(slugify('build@v2!final'), 'build-v2-final');
+});
+test('slugify collapses double hyphens', t => {
+    t.is(slugify('a--b'), 'a-b');
+});
+test('slugify strips leading and trailing hyphens', t => {
+    t.is(slugify('-hello-'), 'hello');
+});
+// ---------------------------------------------------------------------------
+// parsePipelineFile
+// ---------------------------------------------------------------------------
+test('parsePipelineFile parses valid JSON', t => {
+    const result = parsePipelineFile('{"id": "test"}', 'pipeline.json');
+    t.is(result.id, 'test');
+});
+test('parsePipelineFile parses YAML for .yaml extension', t => {
+    const result = parsePipelineFile('id: test', 'pipeline.yaml');
+    t.is(result.id, 'test');
+});
+test('parsePipelineFile parses YAML for .yml extension', t => {
+    const result = parsePipelineFile('id: test', 'pipeline.yml');
+    t.is(result.id, 'test');
+});
+test('parsePipelineFile throws on invalid JSON', t => {
+    t.throws(() => parsePipelineFile('{invalid', 'pipeline.json'));
+});
+// ---------------------------------------------------------------------------
+// mergeEnv
+// ---------------------------------------------------------------------------
+test('mergeEnv returns undefined when both are undefined', t => {
+    t.is(mergeEnv(undefined, undefined), undefined);
+});
+test('mergeEnv returns kit env when user is undefined', t => {
+    t.deepEqual(mergeEnv({ A: '1' }, undefined), { A: '1' });
+});
+test('mergeEnv returns user env when kit is undefined', t => {
+    t.deepEqual(mergeEnv(undefined, { B: '2' }), { B: '2' });
+});
+test('mergeEnv user overrides kit', t => {
+    t.deepEqual(mergeEnv({ A: '1' }, { A: '2' }), { A: '2' });
+});
+test('mergeEnv merges both', t => {
+    t.deepEqual(mergeEnv({ A: '1' }, { B: '2' }), { A: '1', B: '2' });
+});
+// ---------------------------------------------------------------------------
+// mergeCaches
+// ---------------------------------------------------------------------------
+test('mergeCaches returns undefined when both are undefined', t => {
+    t.is(mergeCaches(undefined, undefined), undefined);
+});
+test('mergeCaches concatenates non-overlapping caches', t => {
+    const result = mergeCaches([{ name: 'a', path: '/a' }], [{ name: 'b', path: '/b' }]);
+    t.deepEqual(result, [
+        { name: 'a', path: '/a' },
+        { name: 'b', path: '/b' }
+    ]);
+});
+test('mergeCaches user wins on same name', t => {
+    const result = mergeCaches([{ name: 'x', path: '/kit' }], [{ name: 'x', path: '/user' }]);
+    t.deepEqual(result, [{ name: 'x', path: '/user' }]);
+});
+// ---------------------------------------------------------------------------
+// mergeMounts
+// ---------------------------------------------------------------------------
+test('mergeMounts returns undefined when both are undefined', t => {
+    t.is(mergeMounts(undefined, undefined), undefined);
+});
+test('mergeMounts concatenates mounts', t => {
+    const result = mergeMounts([{ host: 'a', container: '/a' }], [{ host: 'b', container: '/b' }]);
+    t.deepEqual(result, [
+        { host: 'a', container: '/a' },
+        { host: 'b', container: '/b' }
+    ]);
+});
+// ---------------------------------------------------------------------------
+// PipelineLoader.parse
+// ---------------------------------------------------------------------------
+const loader = new PipelineLoader();
+test('parse: valid pipeline with raw steps', t => {
+    const pipeline = loader.parse(JSON.stringify({
+        id: 'my-pipeline',
+        steps: [{
+                id: 'step1',
+                image: 'alpine',
+                cmd: ['echo', 'hello']
+            }]
+    }), 'p.json');
+    t.is(pipeline.id, 'my-pipeline');
+    t.is(pipeline.steps.length, 1);
+    t.is(pipeline.steps[0].id, 'step1');
+});
+test('parse: derives id from name via slugify', t => {
+    const pipeline = loader.parse(JSON.stringify({
+        name: 'Mon Pipeline',
+        steps: [{
+                name: 'Première Étape',
+                image: 'alpine',
+                cmd: ['echo']
+            }]
+    }), 'p.json');
+    t.is(pipeline.id, 'mon-pipeline');
+    t.is(pipeline.steps[0].id, 'premiere-etape');
+});
+test('parse: throws ValidationError when neither id nor name on pipeline', t => {
+    const error = t.throws(() => loader.parse(JSON.stringify({
+        steps: [{ id: 's', image: 'alpine', cmd: ['echo'] }]
+    }), 'p.json'), { message: /at least one of "id" or "name"/ });
+    t.true(error instanceof ValidationError);
+});
+test('parse: throws ValidationError when neither id nor name on step', t => {
+    const error = t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{ image: 'alpine', cmd: ['echo'] }]
+    }), 'p.json'), { message: /at least one of "id" or "name"/ });
+    t.true(error instanceof ValidationError);
+});
+test('parse: throws ValidationError on empty steps array', t => {
+    const error = t.throws(() => loader.parse(JSON.stringify({
+        id: 'p', steps: []
+    }), 'p.json'), { message: /steps must be a non-empty array/ });
+    t.true(error instanceof ValidationError);
+});
+test('parse: throws on invalid identifier with path traversal', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{ id: '../bad', image: 'alpine', cmd: ['echo'] }]
+    }), 'p.json'), { message: /must contain only alphanumeric/ });
+});
+test('parse: throws on invalid identifier with special chars', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{ id: 'hello world', image: 'alpine', cmd: ['echo'] }]
+    }), 'p.json'), { message: /must contain only alphanumeric/ });
+});
+test('parse: throws when step has no image', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{ id: 's', cmd: ['echo'] }]
+    }), 'p.json'), { message: /image is required/ });
+});
+test('parse: throws when step has no cmd', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{ id: 's', image: 'alpine' }]
+    }), 'p.json'), { message: /cmd must be a non-empty array/ });
+});
+test('parse: throws ValidationError on duplicate step ids', t => {
+    const error = t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [
+            { id: 's', image: 'alpine', cmd: ['echo'] },
+            { id: 's', image: 'alpine', cmd: ['echo'] }
+        ]
+    }), 'p.json'), { message: /Duplicate step id/ });
+    t.true(error instanceof ValidationError);
+});
+test('parse: validates mount host must be relative', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{
+                id: 's', image: 'alpine', cmd: ['echo'],
+                mounts: [{ host: '/absolute', container: '/c' }]
+            }]
+    }), 'p.json'), { message: /must be a relative path/ });
+});
+test('parse: allows mount host with ..', t => {
+    t.notThrows(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{
+                id: 's', image: 'alpine', cmd: ['echo'],
+                mounts: [{ host: '../sibling', container: '/c' }]
+            }]
+    }), 'p.json'));
+});
+test('parse: validates mount container must be absolute', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{
+                id: 's', image: 'alpine', cmd: ['echo'],
+                mounts: [{ host: 'src', container: 'relative' }]
+            }]
+    }), 'p.json'), { message: /must be an absolute path/ });
+});
+test('parse: validates cache path must be absolute', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{
+                id: 's', image: 'alpine', cmd: ['echo'],
+                caches: [{ name: 'c', path: 'relative' }]
+            }]
+    }), 'p.json'), { message: /must be an absolute path/ });
+});
+test('parse: validates cache name is a valid identifier', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{
+                id: 's', image: 'alpine', cmd: ['echo'],
+                caches: [{ name: 'bad name!', path: '/cache' }]
+            }]
+    }), 'p.json'), { message: /must contain only alphanumeric/ });
+});
+test('parse: resolves kit step (uses → image/cmd)', t => {
+    const pipeline = loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [{
+                id: 'b',
+                uses: 'shell',
+                with: { run: 'echo hello' }
+            }]
+    }), 'p.json');
+    t.is(pipeline.steps[0].image, 'alpine:3.20');
+    t.deepEqual(pipeline.steps[0].cmd, ['sh', '-c', 'echo hello']);
+});
+// ---------------------------------------------------------------------------
+// DAG validation
+// ---------------------------------------------------------------------------
+test('parse: detects cycle → CyclicDependencyError', t => {
+    const error = t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [
+            { id: 'a', image: 'alpine', cmd: ['echo'], inputs: [{ step: 'b' }] },
+            { id: 'b', image: 'alpine', cmd: ['echo'], inputs: [{ step: 'a' }] }
+        ]
+    }), 'p.json'), { message: /cycle/ });
+    t.true(error instanceof CyclicDependencyError);
+});
+test('parse: missing input ref → error', t => {
+    t.throws(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [
+            { id: 'a', image: 'alpine', cmd: ['echo'], inputs: [{ step: 'missing' }] }
+        ]
+    }), 'p.json'), { message: /unknown step 'missing'/ });
+});
+test('parse: optional input to unknown step → OK', t => {
+    t.notThrows(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [
+            { id: 'a', image: 'alpine', cmd: ['echo'], inputs: [{ step: 'missing', optional: true }] }
+        ]
+    }), 'p.json'));
+});
+test('parse: valid DAG diamond → OK', t => {
+    t.notThrows(() => loader.parse(JSON.stringify({
+        id: 'p',
+        steps: [
+            { id: 'a', image: 'alpine', cmd: ['echo'] },
+            { id: 'b', image: 'alpine', cmd: ['echo'], inputs: [{ step: 'a' }] },
+            { id: 'c', image: 'alpine', cmd: ['echo'], inputs: [{ step: 'a' }] },
+            { id: 'd', image: 'alpine', cmd: ['echo'], inputs: [{ step: 'b' }, { step: 'c' }] }
+        ]
+    }), 'p.json'));
+});

package/dist/core/__tests__/pipeline-runner.js

@@ -0,0 +1,257 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stringify as yamlStringify } from 'yaml';
+import test from 'ava';
+import { DockerCliExecutor } from '../../engine/docker-executor.js';
+import { PipelineLoader } from '../pipeline-loader.js';
+import { PipelineRunner } from '../pipeline-runner.js';
+import { Workspace } from '../../engine/workspace.js';
+import { ContainerCrashError } from '../../errors.js';
+import { createTmpDir, isDockerAvailable, noopReporter, recordingReporter } from '../../__tests__/helpers.js';
+const hasDocker = isDockerAvailable();
+const dockerTest = hasDocker ? test : test.skip;
+// -- helpers -----------------------------------------------------------------
+async function writePipeline(dir, config) {
+    const filePath = join(dir, 'pipeline.yaml');
+    await writeFile(filePath, yamlStringify(config), 'utf8');
+    return filePath;
+}
+// -- two-step dependency -----------------------------------------------------
+dockerTest('step B reads step A output via inputs', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'dep-test',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo data > /output/result.txt'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'cat /input/a/result.txt > /output/copy.txt'], inputs: [{ step: 'a' }] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath);
+    // Both steps should have finished (not just "not crashed")
+    const finished = events.filter((e) => e.event === 'STEP_FINISHED');
+    t.is(finished.length, 2);
+    // Verify step B's artifact actually contains step A's output
+    const ws = await Workspace.open(workdir, 'dep-test');
+    const bRunId = finished.find(e => e.step.id === 'b').runId;
+    t.truthy(bRunId);
+    const content = await readFile(join(ws.runArtifactsPath(bRunId), 'copy.txt'), 'utf8');
+    t.is(content.trim(), 'data');
+});
+// -- cache hit on re-run -----------------------------------------------------
+dockerTest('re-running same pipeline skips all steps (cached)', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'cache-hit',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo a > /output/a.txt'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo b > /output/b.txt'] }
+        ]
+    });
+    const loader = new PipelineLoader();
+    const executor = new DockerCliExecutor();
+    // First run — executes
+    await new PipelineRunner(loader, executor, noopReporter, workdir).run(pipelinePath);
+    // Second run — should skip
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(loader, executor, reporter, workdir).run(pipelinePath);
+    const skipped = events.filter(e => e.event === 'STEP_SKIPPED');
+    t.is(skipped.length, 2);
+});
+// -- cache invalidation cascade ----------------------------------------------
+dockerTest('modifying step A cmd re-executes both steps', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const loader = new PipelineLoader();
+    const executor = new DockerCliExecutor();
+    // First run
+    const path1 = await writePipeline(tmpDir, {
+        id: 'cascade',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo v1 > /output/a.txt'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'cat /input/a/a.txt > /output/b.txt'], inputs: [{ step: 'a' }] }
+        ]
+    });
+    await new PipelineRunner(loader, executor, noopReporter, workdir).run(path1);
+    // Modify step A cmd
+    const path2 = await writePipeline(tmpDir, {
+        id: 'cascade',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo v2 > /output/a.txt'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'cat /input/a/a.txt > /output/b.txt'], inputs: [{ step: 'a' }] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(loader, executor, reporter, workdir).run(path2);
+    // Both steps should have executed (STEP_STARTING events, not STEP_SKIPPED)
+    const starting = events.filter(e => e.event === 'STEP_STARTING');
+    const skipped = events.filter(e => e.event === 'STEP_SKIPPED');
+    t.is(starting.length, 2);
+    t.is(skipped.length, 0);
+});
+// -- allowFailure ------------------------------------------------------------
+dockerTest('step B executes even when step A fails with allowFailure', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'allow-fail',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'exit 1'], allowFailure: true },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo ok > /output/b.txt'] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath);
+    // Step B should have finished successfully
+    const finished = events.filter(e => e.event === 'STEP_FINISHED');
+    t.true(finished.some(e => e.event === 'STEP_FINISHED' && e.step.id === 'b'));
+});
+// -- force specific step -----------------------------------------------------
+dockerTest('force specific step re-executes only that step', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'force-one',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo a > /output/a.txt'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo b > /output/b.txt'] }
+        ]
+    });
+    const loader = new PipelineLoader();
+    const executor = new DockerCliExecutor();
+    // First run
+    await new PipelineRunner(loader, executor, noopReporter, workdir).run(pipelinePath);
+    // Second run with force on step b only
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(loader, executor, reporter, workdir).run(pipelinePath, { force: ['b'] });
+    const skipped = events.filter((e) => e.event === 'STEP_SKIPPED');
+    const starting = events.filter((e) => e.event === 'STEP_STARTING');
+    t.is(skipped.length, 1);
+    t.is(skipped[0].step.id, 'a');
+    t.is(starting.length, 1);
+    t.is(starting[0].step.id, 'b');
+});
+// -- dry run -----------------------------------------------------------------
+dockerTest('dryRun emits STEP_WOULD_RUN without executing or committing', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'dry-run',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo a > /output/a.txt'] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath, { dryRun: true });
+    t.truthy(events.find(e => e.event === 'STEP_WOULD_RUN'));
+    t.falsy(events.find(e => e.event === 'STEP_STARTING'));
+    // No runs should have been committed to disk
+    const ws = await Workspace.open(workdir, 'dry-run');
+    const runs = await ws.listRuns();
+    t.is(runs.length, 0);
+});
+// -- diamond DAG A→B, A→C, B+C→D --------------------------------------------
+dockerTest('diamond DAG executes all steps in correct order', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'diamond',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo a > /output/a.txt'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'cat /input/a/a.txt > /output/b.txt'], inputs: [{ step: 'a' }] },
+            { id: 'c', image: 'alpine:3.20', cmd: ['sh', '-c', 'cat /input/a/a.txt > /output/c.txt'], inputs: [{ step: 'a' }] },
+            { id: 'd', image: 'alpine:3.20', cmd: ['sh', '-c', 'cat /input/b/b.txt /input/c/c.txt > /output/d.txt'], inputs: [{ step: 'b' }, { step: 'c' }] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath);
+    const finished = events.filter((e) => e.event === 'STEP_FINISHED');
+    t.is(finished.length, 4);
+});
+// -- failed step → dependents skipped ----------------------------------------
+dockerTest('failed step causes dependents to be skipped with reason dependency', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'fail-dep',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'exit 1'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo b > /output/b.txt'], inputs: [{ step: 'a' }] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await t.throwsAsync(async () => new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath), { instanceOf: ContainerCrashError });
+    const skipped = events.filter((e) => e.event === 'STEP_SKIPPED');
+    t.is(skipped.length, 1);
+    t.is(skipped[0].step.id, 'b');
+    t.is(skipped[0].reason, 'dependency');
+});
+// -- optional input → step runs despite missing input ------------------------
+dockerTest('optional input allows step to run when input step is missing', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'opt-input',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'exit 1'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo b > /output/b.txt'], inputs: [{ step: 'a', optional: true }] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await t.throwsAsync(async () => new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath));
+    // Step b should have been attempted (STEP_STARTING)
+    const starting = events.filter((e) => e.event === 'STEP_STARTING');
+    t.true(starting.some(e => e.step.id === 'b'));
+});
+// -- if condition → step skipped ---------------------------------------------
+dockerTest('if: "1 == 2" skips step with reason condition', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'cond-skip',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo a > /output/a.txt'], if: '1 == 2' }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath);
+    const skipped = events.filter((e) => e.event === 'STEP_SKIPPED');
+    t.is(skipped.length, 1);
+    t.is(skipped[0].reason, 'condition');
+});
+// -- --target → only subgraph executes ---------------------------------------
+dockerTest('--target executes only the targeted step and its dependencies', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'target-test',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo a > /output/a.txt'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo b > /output/b.txt'], inputs: [{ step: 'a' }] },
+            { id: 'c', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo c > /output/c.txt'] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath, { target: ['b'] });
+    const finished = events.filter((e) => e.event === 'STEP_FINISHED');
+    const executedIds = finished.map(e => e.step.id).sort();
+    t.deepEqual(executedIds, ['a', 'b']);
+});
+// -- independent steps → parallel execution ----------------------------------
+dockerTest('independent steps both finish (parallel execution)', async (t) => {
+    const tmpDir = await createTmpDir();
+    const workdir = await createTmpDir();
+    const pipelinePath = await writePipeline(tmpDir, {
+        id: 'parallel',
+        steps: [
+            { id: 'a', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo a > /output/a.txt'] },
+            { id: 'b', image: 'alpine:3.20', cmd: ['sh', '-c', 'echo b > /output/b.txt'] }
+        ]
+    });
+    const { reporter, events } = recordingReporter();
+    await new PipelineRunner(new PipelineLoader(), new DockerCliExecutor(), reporter, workdir).run(pipelinePath);
+    const finished = events.filter((e) => e.event === 'STEP_FINISHED');
+    t.is(finished.length, 2);
+});

package/dist/core/__tests__/state-persistence.js

@@ -0,0 +1,80 @@
+import test from 'ava';
+import { StateManager } from '../state.js';
+import { createTmpDir } from '../../__tests__/helpers.js';
+// -- load / save round-trip --------------------------------------------------
+test('load on missing file gives empty state, getStep returns undefined', async (t) => {
+    const root = await createTmpDir();
+    const sm = new StateManager(root);
+    await sm.load();
+    t.is(sm.getStep('any'), undefined);
+});
+test('setStep + save + new instance load returns same data', async (t) => {
+    const root = await createTmpDir();
+    const sm1 = new StateManager(root);
+    await sm1.load();
+    sm1.setStep('build', 'run-1', 'fp-abc');
+    await sm1.save();
+    const sm2 = new StateManager(root);
+    await sm2.load();
+    const step = sm2.getStep('build');
+    t.truthy(step);
+    t.is(step.runId, 'run-1');
+    t.is(step.fingerprint, 'fp-abc');
+});
+test('removeStep + save + load removes the step', async (t) => {
+    const root = await createTmpDir();
+    const sm1 = new StateManager(root);
+    await sm1.load();
+    sm1.setStep('build', 'run-1', 'fp-1');
+    sm1.setStep('test', 'run-2', 'fp-2');
+    await sm1.save();
+    const sm2 = new StateManager(root);
+    await sm2.load();
+    sm2.removeStep('build');
+    await sm2.save();
+    const sm3 = new StateManager(root);
+    await sm3.load();
+    t.is(sm3.getStep('build'), undefined);
+    t.truthy(sm3.getStep('test'));
+});
+test('listSteps survives save/load round-trip', async (t) => {
+    const root = await createTmpDir();
+    const sm1 = new StateManager(root);
+    await sm1.load();
+    sm1.setStep('a', 'run-a', 'fp-a');
+    sm1.setStep('b', 'run-b', 'fp-b');
+    await sm1.save();
+    const sm2 = new StateManager(root);
+    await sm2.load();
+    const steps = sm2.listSteps();
+    t.is(steps.length, 2);
+    t.truthy(steps.find(s => s.stepId === 'a' && s.runId === 'run-a'));
+    t.truthy(steps.find(s => s.stepId === 'b' && s.runId === 'run-b'));
+});
+test('activeRunIds survives save/load round-trip', async (t) => {
+    const root = await createTmpDir();
+    const sm1 = new StateManager(root);
+    await sm1.load();
+    sm1.setStep('a', 'run-1', 'fp-a');
+    sm1.setStep('b', 'run-2', 'fp-b');
+    await sm1.save();
+    const sm2 = new StateManager(root);
+    await sm2.load();
+    const ids = sm2.activeRunIds();
+    t.true(ids.has('run-1'));
+    t.true(ids.has('run-2'));
+    t.is(ids.size, 2);
+});
+test('overwriting same stepId keeps only latest after reload', async (t) => {
+    const root = await createTmpDir();
+    const sm1 = new StateManager(root);
+    await sm1.load();
+    sm1.setStep('build', 'run-old', 'fp-old');
+    sm1.setStep('build', 'run-new', 'fp-new');
+    await sm1.save();
+    const sm2 = new StateManager(root);
+    await sm2.load();
+    const step = sm2.getStep('build');
+    t.is(step.runId, 'run-new');
+    t.is(step.fingerprint, 'fp-new');
+});

package/dist/core/__tests__/state.js

@@ -0,0 +1,58 @@
+import test from 'ava';
+import { StateManager } from '../state.js';
+const base = {
+    image: 'alpine:3.20',
+    cmd: ['echo', 'hello']
+};
+test('fingerprint is deterministic', t => {
+    const a = StateManager.fingerprint(base);
+    const b = StateManager.fingerprint(base);
+    t.is(a, b);
+});
+test('fingerprint sorts env keys', t => {
+    const a = StateManager.fingerprint({ ...base, env: { A: '1', B: '2' } });
+    const b = StateManager.fingerprint({ ...base, env: { B: '2', A: '1' } });
+    t.is(a, b);
+});
+test('fingerprint sorts inputRunIds', t => {
+    const a = StateManager.fingerprint({ ...base, inputRunIds: ['x', 'y'] });
+    const b = StateManager.fingerprint({ ...base, inputRunIds: ['y', 'x'] });
+    t.is(a, b);
+});
+test('fingerprint sorts mounts by containerPath', t => {
+    const a = StateManager.fingerprint({
+        ...base,
+        mounts: [
+            { hostPath: 'a', containerPath: '/a' },
+            { hostPath: 'b', containerPath: '/b' }
+        ]
+    });
+    const b = StateManager.fingerprint({
+        ...base,
+        mounts: [
+            { hostPath: 'b', containerPath: '/b' },
+            { hostPath: 'a', containerPath: '/a' }
+        ]
+    });
+    t.is(a, b);
+});
+test('fingerprint differs when optional fields absent vs present', t => {
+    const withEnv = StateManager.fingerprint({ ...base, env: { A: '1' } });
+    const without = StateManager.fingerprint(base);
+    t.not(withEnv, without);
+});
+test('fingerprint changes when image changes', t => {
+    const a = StateManager.fingerprint(base);
+    const b = StateManager.fingerprint({ ...base, image: 'node:24' });
+    t.not(a, b);
+});
+test('fingerprint changes when cmd changes', t => {
+    const a = StateManager.fingerprint(base);
+    const b = StateManager.fingerprint({ ...base, cmd: ['echo', 'bye'] });
+    t.not(a, b);
+});
+test('fingerprint changes when env value changes', t => {
+    const a = StateManager.fingerprint({ ...base, env: { A: '1' } });
+    const b = StateManager.fingerprint({ ...base, env: { A: '2' } });
+    t.not(a, b);
+});