@livingdata/pipex 0.0.8 → 0.0.10

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

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+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();
+    const job = { workspaceId: workspace.id, jobId: randomUUID() };
+    return { workspace, state, tmpDir, job };
+}
+// -- minimal execution -------------------------------------------------------
+dockerTest('minimal step writes artifact and returns exitCode 0', async (t) => {
+    const { workspace, state, job } = 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: '/', job });
+    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, job } = 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: '/', job });
+    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, job } = 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: '/', job });
+    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, job } = 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: '/', job });
+    const second = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/', job });
+    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, job } = 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: '/', job });
+    const second = await runner.run({ workspace, state, step, inputs: new Map(), pipelineRoot: '/', force: true, job });
+    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, job } = 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, job });
+    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, job } = 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: '/', job }));
+    t.true(error instanceof ContainerCrashError);
+});
+// -- allowFailure ------------------------------------------------------------
+dockerTest('allowFailure: true commits run with non-zero exitCode', async (t) => {
+    const { workspace, state, job } = 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: '/', job });
+    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/core/__tests__/stream-reporter.js

@@ -0,0 +1,142 @@
+import test from 'ava';
+import { StreamReporter, CompositeReporter } from '../stream-reporter.js';
+import { InMemoryTransport } from '../transport.js';
+const jobId = 'test-job-1';
+const workspaceId = 'ws-1';
+test('publishes non-log events to transport', t => {
+    const transport = new InMemoryTransport();
+    const reporter = new StreamReporter(transport);
+    reporter.emit({ event: 'PIPELINE_START', workspaceId, jobId, pipelineName: 'test', steps: [] });
+    t.is(transport.messages.length, 1);
+    t.is(transport.messages[0].event.event, 'PIPELINE_START');
+    t.is(transport.messages[0].type, 'PIPELINE_START');
+    t.is(transport.messages[0].version, 1);
+});
+test('ignores STEP_LOG events', t => {
+    const transport = new InMemoryTransport();
+    const reporter = new StreamReporter(transport);
+    reporter.emit({
+        event: 'STEP_LOG',
+        workspaceId,
+        jobId,
+        step: { id: 's1', displayName: 's1' },
+        stream: 'stdout',
+        line: 'hello'
+    });
+    t.is(transport.messages.length, 0);
+});
+test('sequence numbers are monotonically increasing', t => {
+    const transport = new InMemoryTransport();
+    const reporter = new StreamReporter(transport);
+    reporter.emit({ event: 'PIPELINE_START', workspaceId, jobId, pipelineName: 'test', steps: [] });
+    reporter.emit({ event: 'STEP_STARTING', workspaceId, jobId, step: { id: 's1', displayName: 's1' } });
+    reporter.emit({ event: 'PIPELINE_FINISHED', workspaceId, jobId, totalArtifactSize: 0 });
+    t.is(transport.messages[0].seq, 0);
+    t.is(transport.messages[1].seq, 1);
+    t.is(transport.messages[2].seq, 2);
+});
+test('timestamp is set on each message', t => {
+    const transport = new InMemoryTransport();
+    const reporter = new StreamReporter(transport);
+    reporter.emit({ event: 'PIPELINE_START', workspaceId, jobId, pipelineName: 'test', steps: [] });
+    t.truthy(transport.messages[0].timestamp);
+    t.regex(transport.messages[0].timestamp, /^\d{4}-\d{2}-\d{2}T/);
+});
+test('flush calls transport.flush', async (t) => {
+    let flushed = false;
+    const transport = {
+        messages: [],
+        async publish(message) {
+            this.messages.push(message);
+        },
+        async flush() {
+            flushed = true;
+        }
+    };
+    const reporter = new StreamReporter(transport);
+    await reporter.flush();
+    t.true(flushed);
+});
+test('CompositeReporter delegates to all reporters', t => {
+    const events1 = [];
+    const events2 = [];
+    const r1 = {
+        emit(e) {
+            events1.push(e);
+        }
+    };
+    const r2 = {
+        emit(e) {
+            events2.push(e);
+        }
+    };
+    const composite = new CompositeReporter(r1, r2);
+    composite.emit({ event: 'PIPELINE_START', workspaceId, jobId, pipelineName: 'test', steps: [] });
+    t.is(events1.length, 1);
+    t.is(events2.length, 1);
+});
+test('CompositeReporter with no reporters does not throw', t => {
+    const composite = new CompositeReporter();
+    t.notThrows(() => {
+        composite.emit({ event: 'PIPELINE_START', workspaceId, jobId, pipelineName: 'test', steps: [] });
+    });
+});
+test('STEP_LOG interleaved with other events does not affect sequence', t => {
+    const transport = new InMemoryTransport();
+    const reporter = new StreamReporter(transport);
+    reporter.emit({ event: 'PIPELINE_START', workspaceId, jobId, pipelineName: 'test', steps: [] });
+    reporter.emit({ event: 'STEP_LOG', workspaceId, jobId, step: { id: 's1', displayName: 's1' }, stream: 'stdout', line: 'ignored' });
+    reporter.emit({ event: 'STEP_LOG', workspaceId, jobId, step: { id: 's1', displayName: 's1' }, stream: 'stderr', line: 'also ignored' });
+    reporter.emit({ event: 'STEP_STARTING', workspaceId, jobId, step: { id: 's1', displayName: 's1' } });
+    t.is(transport.messages.length, 2);
+    t.is(transport.messages[0].seq, 0);
+    t.is(transport.messages[1].seq, 1);
+});
+test('event data is preserved in transport message', t => {
+    const transport = new InMemoryTransport();
+    const reporter = new StreamReporter(transport);
+    const step = { id: 's1', displayName: 'Step One' };
+    reporter.emit({ event: 'STEP_FINISHED', workspaceId, jobId, step, runId: 'run-42', durationMs: 1234, artifactSize: 5678 });
+    const published = transport.messages[0];
+    t.is(published.type, 'STEP_FINISHED');
+    const ev = published.event;
+    t.is(ev.event, 'STEP_FINISHED');
+    if (ev.event === 'STEP_FINISHED') {
+        t.is(ev.runId, 'run-42');
+        t.is(ev.durationMs, 1234);
+        t.is(ev.artifactSize, 5678);
+        t.deepEqual(ev.step, step);
+    }
+});
+test('flush succeeds when transport has no flush method', async (t) => {
+    const transport = new InMemoryTransport();
+    const reporter = new StreamReporter(transport);
+    await t.notThrowsAsync(async () => reporter.flush());
+});
+test('all non-log event types pass through StreamReporter', t => {
+    const transport = new InMemoryTransport();
+    const reporter = new StreamReporter(transport);
+    const step = { id: 's1', displayName: 's1' };
+    reporter.emit({ event: 'PIPELINE_START', workspaceId, jobId, pipelineName: 'test', steps: [step] });
+    reporter.emit({ event: 'STEP_STARTING', workspaceId, jobId, step });
+    reporter.emit({ event: 'STEP_SKIPPED', workspaceId, jobId, step, reason: 'cached' });
+    reporter.emit({ event: 'STEP_FINISHED', workspaceId, jobId, step });
+    reporter.emit({ event: 'STEP_FAILED', workspaceId, jobId, step, exitCode: 1 });
+    reporter.emit({ event: 'STEP_RETRYING', workspaceId, jobId, step, attempt: 1, maxRetries: 3 });
+    reporter.emit({ event: 'STEP_WOULD_RUN', workspaceId, jobId, step });
+    reporter.emit({ event: 'PIPELINE_FINISHED', workspaceId, jobId, totalArtifactSize: 0 });
+    reporter.emit({ event: 'PIPELINE_FAILED', workspaceId, jobId });
+    t.is(transport.messages.length, 9);
+    const types = transport.messages.map(m => m.type);
+    t.deepEqual(types, [
+        'PIPELINE_START',
+        'STEP_STARTING',
+        'STEP_SKIPPED',
+        'STEP_FINISHED',
+        'STEP_FAILED',
+        'STEP_RETRYING',
+        'STEP_WOULD_RUN',
+        'PIPELINE_FINISHED',
+        'PIPELINE_FAILED'
+    ]);
+});

package/dist/core/__tests__/transport.js

@@ -0,0 +1,50 @@
+import test from 'ava';
+import { InMemoryTransport } from '../transport.js';
+function makeMessage(seq, overrides) {
+    const event = {
+        event: 'PIPELINE_START',
+        workspaceId: 'ws-1',
+        jobId: 'job-1',
+        pipelineName: 'test',
+        steps: []
+    };
+    return {
+        seq,
+        timestamp: new Date().toISOString(),
+        version: 1,
+        type: 'PIPELINE_START',
+        event,
+        ...overrides
+    };
+}
+test('publish stores messages in order', async (t) => {
+    const transport = new InMemoryTransport();
+    await transport.publish(makeMessage(0));
+    await transport.publish(makeMessage(1));
+    t.is(transport.messages.length, 2);
+    t.is(transport.messages[0].seq, 0);
+    t.is(transport.messages[1].seq, 1);
+});
+test('clear removes all messages', async (t) => {
+    const transport = new InMemoryTransport();
+    await transport.publish(makeMessage(0));
+    await transport.publish(makeMessage(1));
+    transport.clear();
+    t.is(transport.messages.length, 0);
+});
+test('publish after clear accumulates fresh', async (t) => {
+    const transport = new InMemoryTransport();
+    await transport.publish(makeMessage(0));
+    transport.clear();
+    await transport.publish(makeMessage(5));
+    t.is(transport.messages.length, 1);
+    t.is(transport.messages[0].seq, 5);
+});
+test('message content is preserved through publish', async (t) => {
+    const transport = new InMemoryTransport();
+    const message = makeMessage(0);
+    await transport.publish(message);
+    t.deepEqual(transport.messages[0], message);
+    t.is(transport.messages[0].event.event, 'PIPELINE_START');
+    t.is(transport.messages[0].version, 1);
+});

package/dist/core/__tests__/utils.js

@@ -0,0 +1,40 @@
+import process from 'node:process';
+import { join } from 'node:path';
+import test from 'ava';
+import { ValidationError } from '../../errors.js';
+import { resolveHostPath } from '../utils.js';
+test('resolveHostPath: resolves path within cwd', t => {
+    const cwd = process.cwd();
+    const pipelineRoot = join(cwd, 'pipelines');
+    const result = resolveHostPath(pipelineRoot, '../scripts');
+    t.is(result, join(cwd, 'scripts'));
+});
+test('resolveHostPath: resolves sibling directory with ..', t => {
+    const cwd = process.cwd();
+    const pipelineRoot = join(cwd, 'a', 'b');
+    const result = resolveHostPath(pipelineRoot, '../c');
+    t.is(result, join(cwd, 'a', 'c'));
+});
+test('resolveHostPath: allows path equal to cwd', t => {
+    const cwd = process.cwd();
+    const pipelineRoot = join(cwd, 'sub');
+    const result = resolveHostPath(pipelineRoot, '..');
+    t.is(result, cwd);
+});
+test('resolveHostPath: simple relative path without ..', t => {
+    const cwd = process.cwd();
+    const pipelineRoot = join(cwd, 'pipelines');
+    const result = resolveHostPath(pipelineRoot, 'data');
+    t.is(result, join(cwd, 'pipelines', 'data'));
+});
+test('resolveHostPath: throws when path escapes cwd', t => {
+    const cwd = process.cwd();
+    const error = t.throws(() => resolveHostPath(cwd, '../outside'), { instanceOf: ValidationError });
+    t.truthy(error?.message.includes('outside the working directory'));
+});
+test('resolveHostPath: throws when deeply escaping cwd', t => {
+    const cwd = process.cwd();
+    const pipelineRoot = join(cwd, 'a');
+    const error = t.throws(() => resolveHostPath(pipelineRoot, '../../outside'), { instanceOf: ValidationError });
+    t.truthy(error?.message.includes('outside the working directory'));
+});

package/dist/core/bundle.js

@@ -0,0 +1,130 @@
+import { Buffer } from 'node:buffer';
+import { readFile, mkdir, writeFile, symlink, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, normalize, resolve, sep } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { buffer as streamToBuffer } from 'node:stream/consumers';
+import ignore from 'ignore';
+import * as tar from 'tar';
+import { BundleError } from '../errors.js';
+import { PipelineLoader } from './pipeline-loader.js';
+const MAX_BUNDLE_SIZE = 50 * 1024 * 1024; // 50 MB
+const DEFAULT_IGNORES = [
+    '.git',
+    'node_modules',
+    '__pycache__',
+    '.DS_Store',
+    '*.pyc',
+    '.env'
+];
+const MANIFEST_VERSION = 1;
+function normalizePath(p) {
+    const n = normalize(p);
+    return n.endsWith(sep) ? n.slice(0, -1) : n;
+}
+export function collectDependencies(pipeline) {
+    const paths = new Set();
+    for (const step of pipeline.steps) {
+        if (step.mounts) {
+            for (const mount of step.mounts) {
+                paths.add(normalizePath(mount.host));
+            }
+        }
+        if (step.sources) {
+            for (const source of step.sources) {
+                paths.add(normalizePath(source.host));
+            }
+        }
+    }
+    return [...paths].sort();
+}
+export async function buildIgnoreFilter(pipelineRoot) {
+    const ig = ignore().add(DEFAULT_IGNORES);
+    try {
+        const gitignore = await readFile(resolve(pipelineRoot, '.gitignore'), 'utf8');
+        ig.add(gitignore);
+    }
+    catch { }
+    return (path) => {
+        if (path === '') {
+            return false;
+        }
+        // Test both variants to handle directory-only patterns (e.g. "dist/")
+        // which only match when the path has a trailing slash.
+        return ig.ignores(path) || ig.ignores(path + '/');
+    };
+}
+export async function buildBundle(pipelineFilePath) {
+    const absolutePath = resolve(pipelineFilePath);
+    const pipelineRoot = dirname(absolutePath);
+    const loader = new PipelineLoader();
+    const pipeline = await loader.load(absolutePath);
+    const deps = collectDependencies(pipeline);
+    // Verify all dependencies exist
+    for (const dep of deps) {
+        const depPath = resolve(pipelineRoot, dep);
+        try {
+            await stat(depPath);
+        }
+        catch {
+            throw new BundleError(`Dependency not found: ${dep}`);
+        }
+    }
+    const shouldIgnore = await buildIgnoreFilter(pipelineRoot);
+    const manifest = { version: MANIFEST_VERSION, pipeline };
+    const manifestJson = JSON.stringify(manifest, null, 2) + '\n';
+    // Use a staging directory with symlinks to combine manifest + deps in a single tar
+    const stagingDir = join(tmpdir(), `pipex-bundle-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(stagingDir, { recursive: true });
+    try {
+        // Write manifest
+        await writeFile(join(stagingDir, 'manifest.json'), manifestJson);
+        // Symlink dependencies into staging
+        for (const dep of deps) {
+            const target = join(stagingDir, dep);
+            await mkdir(dirname(target), { recursive: true });
+            await symlink(resolve(pipelineRoot, dep), target);
+        }
+        // Create tar archive
+        const entries = ['manifest.json', ...deps];
+        const stream = tar.create({
+            cwd: stagingDir,
+            gzip: true,
+            follow: true,
+            filter(path) {
+                return !shouldIgnore(path);
+            }
+        }, entries);
+        const archiveBuffer = await streamToBuffer(stream);
+        if (archiveBuffer.length > MAX_BUNDLE_SIZE) {
+            throw new BundleError(`Bundle size (${archiveBuffer.length} bytes) exceeds maximum of ${MAX_BUNDLE_SIZE} bytes`);
+        }
+        return Buffer.from(archiveBuffer);
+    }
+    finally {
+        await rm(stagingDir, { recursive: true, force: true });
+    }
+}
+export async function extractBundle(archive, targetDir) {
+    await mkdir(targetDir, { recursive: true });
+    await pipeline(Readable.from(archive), tar.extract({ cwd: targetDir }));
+    let manifestContent;
+    try {
+        manifestContent = await readFile(resolve(targetDir, 'manifest.json'), 'utf8');
+    }
+    catch {
+        throw new BundleError('Invalid bundle: manifest.json not found');
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestContent);
+    }
+    catch {
+        throw new BundleError('Invalid bundle: manifest.json is not valid JSON');
+    }
+    if (!manifest.pipeline) {
+        throw new BundleError('Invalid bundle: manifest.json missing pipeline');
+    }
+    return manifest.pipeline;
+}

package/dist/core/condition.js

@@ -0,0 +1,11 @@
+import jexlModule from 'jexl';
+const jexl = new jexlModule.Jexl();
+export async function evaluateCondition(expression, context) {
+    try {
+        const result = await jexl.eval(expression, context);
+        return Boolean(result);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/dag.js

@@ -0,0 +1,143 @@
+import { CyclicDependencyError, ValidationError } from '../errors.js';
+/** Build a dependency graph from resolved steps. */
+export function buildGraph(steps) {
+    const graph = new Map();
+    for (const step of steps) {
+        const deps = new Set();
+        if (step.inputs) {
+            for (const input of step.inputs) {
+                deps.add(input.step);
+            }
+        }
+        graph.set(step.id, deps);
+    }
+    return graph;
+}
+/** Validate graph: check for missing refs (non-optional) and cycles. */
+export function validateGraph(graph, steps) {
+    validateReferences(graph, steps);
+    detectCycles(graph);
+}
+function validateReferences(graph, steps) {
+    const optionalInputs = new Set();
+    for (const step of steps) {
+        if (step.inputs) {
+            for (const input of step.inputs) {
+                if (input.optional) {
+                    optionalInputs.add(`${step.id}:${input.step}`);
+                }
+            }
+        }
+    }
+    for (const [stepId, deps] of graph) {
+        for (const dep of deps) {
+            if (!graph.has(dep) && !optionalInputs.has(`${stepId}:${dep}`)) {
+                throw new ValidationError(`Step '${stepId}' references unknown step '${dep}'`);
+            }
+        }
+    }
+}
+function detectCycles(graph) {
+    const inDeg = computeInDegree(graph);
+    const queue = [];
+    for (const [id, deg] of inDeg) {
+        if (deg === 0) {
+            queue.push(id);
+        }
+    }
+    let processed = 0;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        processed++;
+        for (const [id, deps] of graph) {
+            if (deps.has(current)) {
+                const newDeg = inDeg.get(id) - 1;
+                inDeg.set(id, newDeg);
+                if (newDeg === 0) {
+                    queue.push(id);
+                }
+            }
+        }
+    }
+    if (processed < graph.size) {
+        throw new CyclicDependencyError('Pipeline contains a dependency cycle');
+    }
+}
+/** Compute in-degree for each node (number of existing deps). */
+function computeInDegree(graph) {
+    const inDeg = new Map();
+    for (const [id, deps] of graph) {
+        let count = 0;
+        for (const dep of deps) {
+            if (graph.has(dep)) {
+                count++;
+            }
+        }
+        inDeg.set(id, count);
+    }
+    return inDeg;
+}
+/** Return steps grouped by topological level (parallelizable groups). */
+export function topologicalLevels(graph) {
+    const inDeg = computeInDegree(graph);
+    const levels = [];
+    const remaining = new Set(graph.keys());
+    while (remaining.size > 0) {
+        const level = [];
+        for (const id of remaining) {
+            if (inDeg.get(id) === 0) {
+                level.push(id);
+            }
+        }
+        if (level.length === 0) {
+            break; // Cycle — should not happen after validateGraph
+        }
+        levels.push(level);
+        for (const id of level) {
+            remaining.delete(id);
+            for (const [nodeId, deps] of graph) {
+                if (deps.has(id) && remaining.has(nodeId)) {
+                    inDeg.set(nodeId, inDeg.get(nodeId) - 1);
+                }
+            }
+        }
+    }
+    return levels;
+}
+/** BFS backward from targets to collect all ancestors + targets. */
+export function subgraph(graph, targets) {
+    const result = new Set();
+    const queue = [...targets];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (result.has(current)) {
+            continue;
+        }
+        result.add(current);
+        const deps = graph.get(current);
+        if (deps) {
+            for (const dep of deps) {
+                if (!result.has(dep)) {
+                    queue.push(dep);
+                }
+            }
+        }
+    }
+    return result;
+}
+/** Return steps that no other step depends on (leaf/terminal nodes). */
+export function leafNodes(graph) {
+    const depended = new Set();
+    for (const deps of graph.values()) {
+        for (const dep of deps) {
+            depended.add(dep);
+        }
+    }
+    const leaves = [];
+    for (const id of graph.keys()) {
+        if (!depended.has(id)) {
+            leaves.push(id);
+        }
+    }
+    return leaves;
+}

package/dist/core/env-file.js

@@ -0,0 +1,6 @@
+import { readFile } from 'node:fs/promises';
+import { parse } from 'dotenv';
+export async function loadEnvFile(filePath) {
+    const content = await readFile(filePath, 'utf8');
+    return parse(content);
+}