@livingdata/pipex 0.0.8 → 0.0.10

package/dist/cli/__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/cli/__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/cli/__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);
+});

package/dist/cli/__tests__/step-runner.js

@@ -0,0 +1,116 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import test from 'ava';
+import { Workspace } from '../../engine/workspace.js';
+import { DockerCliExecutor } from '../../engine/docker-executor.js';
+import { ContainerCrashError } from '../../errors.js';
+import { StateManager } from '../state.js';
+import { StepRunner } from '../step-runner.js';
+import { createTmpDir, isDockerAvailable, noopReporter, recordingReporter } from '../../__tests__/helpers.js';
+const hasDocker = isDockerAvailable();
+const dockerTest = hasDocker ? test : test.skip;
+// -- helpers -----------------------------------------------------------------
+function makeStep(overrides) {
+    return {
+        image: 'alpine:3.20',
+        cmd: ['sh', '-c', 'echo hello'],
+        ...overrides
+    };
+}
+async function setupWorkspace() {
+    const tmpDir = await createTmpDir();
+    const workspace = await Workspace.create(tmpDir, 'test-ws');
+    const state = new StateManager(workspace.root);
+    await state.load();
+    return { workspace, state, tmpDir };
+}
+// -- minimal execution -------------------------------------------------------
+dockerTest('minimal step writes artifact and returns exitCode 0', async (t) => {
+    const { workspace, state } = await setupWorkspace();
+    const runner = new StepRunner(new DockerCliExecutor(), noopReporter);
+    const step = makeStep({ id: 'greet', cmd: ['sh', '-c', 'echo hello > /output/greeting.txt'] });
+    const result = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/' });
+    t.is(result.exitCode, 0);
+    t.truthy(result.runId);
+    // Artifact exists in committed run
+    const content = await readFile(join(workspace.runArtifactsPath(result.runId), 'greeting.txt'), 'utf8');
+    t.is(content.trim(), 'hello');
+});
+dockerTest('meta.json exists with correct fields', async (t) => {
+    const { workspace, state } = await setupWorkspace();
+    const runner = new StepRunner(new DockerCliExecutor(), noopReporter);
+    const step = makeStep({ id: 'meta-test', cmd: ['sh', '-c', 'echo ok > /output/out.txt'] });
+    const result = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/' });
+    const metaPath = join(workspace.runPath(result.runId), 'meta.json');
+    const meta = JSON.parse(await readFile(metaPath, 'utf8'));
+    t.is(meta.runId, result.runId);
+    t.is(meta.exitCode, 0);
+    t.is(meta.image, 'alpine:3.20');
+    t.deepEqual(meta.cmd, ['sh', '-c', 'echo ok > /output/out.txt']);
+});
+// -- log capture -------------------------------------------------------------
+dockerTest('stdout and stderr are captured to log files', async (t) => {
+    const { workspace, state } = await setupWorkspace();
+    const runner = new StepRunner(new DockerCliExecutor(), noopReporter);
+    const step = makeStep({ id: 'logs', cmd: ['sh', '-c', 'echo out-line && echo err-line >&2'] });
+    const result = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/' });
+    const stdout = await readFile(join(workspace.runPath(result.runId), 'stdout.log'), 'utf8');
+    const stderr = await readFile(join(workspace.runPath(result.runId), 'stderr.log'), 'utf8');
+    t.true(stdout.includes('out-line'));
+    t.true(stderr.includes('err-line'));
+});
+// -- cache hit ---------------------------------------------------------------
+dockerTest('second run of same step is cached (STEP_SKIPPED)', async (t) => {
+    const { workspace, state } = await setupWorkspace();
+    const { reporter, events } = recordingReporter();
+    const runner = new StepRunner(new DockerCliExecutor(), reporter);
+    const step = makeStep({ id: 'cached', cmd: ['sh', '-c', 'echo hi > /output/x.txt'] });
+    const first = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/' });
+    const second = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/' });
+    t.is(first.runId, second.runId);
+    const skipped = events.find(e => e.event === 'STEP_SKIPPED');
+    t.truthy(skipped);
+    t.is(skipped.reason, 'cached');
+});
+// -- force -------------------------------------------------------------------
+dockerTest('force: true produces new runId', async (t) => {
+    const { workspace, state } = await setupWorkspace();
+    const runner = new StepRunner(new DockerCliExecutor(), noopReporter);
+    const step = makeStep({ id: 'force-test', cmd: ['sh', '-c', 'echo data > /output/f.txt'] });
+    const first = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/' });
+    const second = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/', force: true });
+    t.not(first.runId, second.runId);
+    t.is(second.exitCode, 0);
+});
+// -- ephemeral ---------------------------------------------------------------
+dockerTest('ephemeral: true returns exitCode but no runId', async (t) => {
+    const { workspace, state } = await setupWorkspace();
+    const runner = new StepRunner(new DockerCliExecutor(), noopReporter);
+    const step = makeStep({ id: 'ephemeral', cmd: ['sh', '-c', 'echo temp > /output/t.txt'] });
+    const result = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/', ephemeral: true });
+    t.is(result.exitCode, 0);
+    t.is(result.runId, undefined);
+    // No run committed
+    const runs = await workspace.listRuns();
+    t.is(runs.length, 0);
+});
+// -- failure -----------------------------------------------------------------
+dockerTest('non-zero exit throws ContainerCrashError', async (t) => {
+    const { workspace, state } = await setupWorkspace();
+    const runner = new StepRunner(new DockerCliExecutor(), noopReporter);
+    const step = makeStep({ id: 'fail', cmd: ['sh', '-c', 'exit 1'] });
+    const error = await t.throwsAsync(async () => runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/' }));
+    t.true(error instanceof ContainerCrashError);
+});
+// -- allowFailure ------------------------------------------------------------
+dockerTest('allowFailure: true commits run with non-zero exitCode', async (t) => {
+    const { workspace, state } = await setupWorkspace();
+    const runner = new StepRunner(new DockerCliExecutor(), noopReporter);
+    const step = makeStep({ id: 'allow-fail', cmd: ['sh', '-c', 'exit 1'], allowFailure: true });
+    const result = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/' });
+    t.truthy(result.runId);
+    t.is(result.exitCode, 1);
+    // Run was committed
+    const runs = await workspace.listRuns();
+    t.true(runs.includes(result.runId));
+});

package/dist/cli/commands/bundle.js

@@ -0,0 +1,35 @@
+import process from 'node:process';
+import { writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import chalk from 'chalk';
+import { buildBundle } from '../../core/bundle.js';
+import { PipelineLoader } from '../../core/pipeline-loader.js';
+import { formatSize } from '../../core/utils.js';
+export function registerBundleCommand(program) {
+    program
+        .command('bundle')
+        .description('Package a pipeline and its local dependencies into a tar.gz archive')
+        .argument('<pipeline>', 'Path to the pipeline file')
+        .option('-o, --output <path>', 'Output file path (default: <pipeline-id>.tar.gz)')
+        .action(async (pipelineFile, options) => {
+        try {
+            const pipelinePath = resolve(pipelineFile);
+            // Determine output path
+            let outputPath = options.output;
+            if (!outputPath) {
+                const loader = new PipelineLoader();
+                const pipeline = await loader.load(pipelinePath);
+                outputPath = `${pipeline.id}.tar.gz`;
+            }
+            outputPath = resolve(outputPath);
+            const archive = await buildBundle(pipelinePath);
+            await writeFile(outputPath, archive);
+            console.log(chalk.green(`Bundle created: ${basename(outputPath)} (${formatSize(archive.length)})`));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(chalk.red(`Bundle failed: ${message}`));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/cat.js

@@ -0,0 +1,54 @@
+import process from 'node:process';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import chalk from 'chalk';
+import { Workspace } from '../../engine/workspace.js';
+import { StateManager } from '../../core/state.js';
+import { getGlobalOptions } from '../utils.js';
+export function registerCatCommand(program) {
+    program
+        .command('cat')
+        .description('Read artifact content from a step\'s latest run')
+        .argument('<workspace>', 'Workspace name')
+        .argument('<step>', 'Step ID')
+        .argument('[path]', 'Path within artifacts (omit to list)')
+        .action(async (workspaceName, stepId, artifactPath, _options, cmd) => {
+        const { workdir } = getGlobalOptions(cmd);
+        const workdirRoot = resolve(workdir);
+        const workspace = await Workspace.open(workdirRoot, workspaceName);
+        const state = new StateManager(workspace.root);
+        await state.load();
+        const stepState = state.getStep(stepId);
+        if (!stepState) {
+            console.error(chalk.red(`No run found for step: ${stepId}`));
+            process.exitCode = 1;
+            return;
+        }
+        const artifactsDir = workspace.runArtifactsPath(stepState.runId);
+        const targetPath = artifactPath ? join(artifactsDir, artifactPath) : artifactsDir;
+        // Prevent path traversal
+        if (!targetPath.startsWith(artifactsDir)) {
+            console.error(chalk.red('Invalid path: must be within artifacts directory'));
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const info = await stat(targetPath);
+            if (info.isDirectory()) {
+                const entries = await readdir(targetPath, { withFileTypes: true });
+                for (const entry of entries) {
+                    const suffix = entry.isDirectory() ? '/' : '';
+                    console.log(entry.name + suffix);
+                }
+            }
+            else {
+                const content = await readFile(targetPath);
+                process.stdout.write(content);
+            }
+        }
+        catch {
+            console.error(chalk.red(`Not found: ${artifactPath ?? '(artifacts directory)'}`));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/clean.js

@@ -0,0 +1,22 @@
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { Workspace } from '../../engine/workspace.js';
+import { getGlobalOptions } from '../utils.js';
+export function registerCleanCommand(program) {
+    program
+        .command('clean')
+        .description('Remove all workspaces')
+        .action(async (_options, cmd) => {
+        const { workdir } = getGlobalOptions(cmd);
+        const workdirRoot = resolve(workdir);
+        const names = await Workspace.list(workdirRoot);
+        if (names.length === 0) {
+            console.log(chalk.gray('No workspaces to clean.'));
+            return;
+        }
+        for (const name of names) {
+            await Workspace.remove(workdirRoot, name);
+        }
+        console.log(chalk.green(`Removed ${names.length} workspace${names.length > 1 ? 's' : ''}.`));
+    });
+}