@michaelthielemann/kestrel 4.1.2 → 5.0.0

package/dist/load.js

@@ -0,0 +1,79 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readdir, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { KestrelBootError } from "./errors.js";
+async function importDefault(file, owner) {
+    let mod;
+    try {
+        mod = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    }
+    catch (err) {
+        throw new KestrelBootError(owner, `cannot load ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const def = mod.default;
+    if (def === undefined)
+        throw new KestrelBootError(owner, `${file} has no default export`);
+    return def;
+}
+export async function loadConfig(file) {
+    const def = await importDefault(file, "kestrel.config");
+    if (typeof def !== "object" || def === null)
+        throw new KestrelBootError("kestrel.config", "default export is not an object");
+    return def;
+}
+export function resolveModuleFile(root, use) {
+    if (use.startsWith("./") || use.startsWith("../") || isAbsolute(use))
+        return resolve(root, use);
+    return createRequire(pathToFileURL(resolve(root, "package.json")).href).resolve(use);
+}
+export async function loadModules(root, config) {
+    const out = [];
+    for (const entry of config.modules) {
+        let file;
+        try {
+            file = resolveModuleFile(root, entry.use);
+        }
+        catch (err) {
+            throw new KestrelBootError(entry.use, `cannot resolve module: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const def = await importDefault(file, entry.use);
+        const m = def;
+        if (typeof m !== "object" || m === null || typeof m.name !== "string" || typeof m.setup !== "function" || !Array.isArray(m.provides) || !Array.isArray(m.requires) || m.configSchema === undefined) {
+            throw new KestrelBootError(entry.use, "default export is not a defineModule() result");
+        }
+        out.push(m);
+    }
+    return out;
+}
+export async function loadPipelines(root, dir) {
+    const abs = resolve(root, dir);
+    try {
+        if (!(await stat(abs)).isDirectory())
+            throw new KestrelBootError("pipelines", `${abs} is not a directory`);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const files = (await readdir(abs)).filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts")).sort();
+    const out = [];
+    for (const file of files) {
+        const def = await importDefault(resolve(abs, file), `pipelines/${file}`);
+        const p = def;
+        if (typeof p !== "object" || p === null || typeof p.name !== "string" || !Array.isArray(p.steps)) {
+            throw new KestrelBootError(`pipelines/${file}`, "default export is not a definePipeline() result");
+        }
+        out.push(p);
+    }
+    return out;
+}

package/dist/logger.d.ts

@@ -0,0 +1,18 @@
+export interface StepLog {
+    runId: string;
+    parentRunId?: string;
+    pipeline: string;
+    step: string;
+    ms: number;
+    outcome: "ok" | `fail(${string})` | "error";
+}
+export interface Logger {
+    step(entry: StepLog): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn?(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+export declare function logWarn(logger: Logger, message: string, data?: Record<string, unknown>): void;
+export declare function localIso(date: Date): string;
+export declare const consoleLogger: Logger;
+export declare const silentLogger: Logger;

package/dist/logger.js

@@ -0,0 +1,36 @@
+export function logWarn(logger, message, data) {
+    if (logger.warn)
+        logger.warn(message, data);
+    else
+        logger.info(message, data);
+}
+// ISO 8601 with the local UTC offset (not "Z"), since consoleLogger runs on one machine
+// and log lines should read in local time without losing offset information.
+export function localIso(date) {
+    const pad = (n, width = 2) => String(n).padStart(width, "0");
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const abs = Math.abs(offsetMinutes);
+    const offset = `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}${offset}`;
+}
+export const consoleLogger = {
+    step(entry) {
+        console.log(JSON.stringify({ time: localIso(new Date()), level: "step", ...entry }));
+    },
+    info(message, data = {}) {
+        console.log(JSON.stringify({ time: localIso(new Date()), level: "info", message, ...data }));
+    },
+    warn(message, data = {}) {
+        console.warn(JSON.stringify({ time: localIso(new Date()), level: "warn", message, ...data }));
+    },
+    error(message, data = {}) {
+        console.error(JSON.stringify({ time: localIso(new Date()), level: "error", message, ...data }));
+    },
+};
+export const silentLogger = {
+    step() { },
+    info() { },
+    warn() { },
+    error() { },
+};

package/dist/registry.d.ts

@@ -0,0 +1,14 @@
+import { type Step, type StepMap } from "./context.ts";
+import type { StepDescription, StepDescriptions } from "./defineModule.ts";
+export interface ResolvedStep {
+    name: string;
+    fn: Step;
+    description: StepDescription;
+}
+export declare class StepRegistry {
+    private readonly entries;
+    register(owner: string, prefix: string, steps: StepMap, descriptions?: StepDescriptions): void;
+    has(name: string): boolean;
+    names(): string[];
+    resolve(spec: string, owner?: string): ResolvedStep;
+}

package/dist/registry.js

@@ -0,0 +1,87 @@
+import { isStepFactory } from "./context.js";
+import { KestrelBootError } from "./errors.js";
+const CONTEXT_PATH = /^[a-zA-Z][A-Za-z0-9]*(\.[A-Za-z0-9_-]+)*\??$/;
+// Walks the prototype chain (like `missingMethods` in defineContract.ts, via
+// property access) so a class-instance step map registers its inherited methods too.
+function stepKeys(steps) {
+    const keys = new Set();
+    for (let obj = steps; obj && obj !== Object.prototype; obj = Object.getPrototypeOf(obj)) {
+        for (const key of Object.getOwnPropertyNames(obj)) {
+            if (key !== "constructor")
+                keys.add(key);
+        }
+    }
+    return [...keys];
+}
+function checkPaths(owner, name, description) {
+    for (const path of description.reads) {
+        if (path.endsWith("?"))
+            throw new KestrelBootError(owner, `step "${name}" reads "${path}"; the trailing "?" is allowed in writes only`);
+        if (!CONTEXT_PATH.test(path))
+            throw new KestrelBootError(owner, `step "${name}" declares an invalid read path "${path}"`);
+    }
+    for (const path of description.writes) {
+        if (!CONTEXT_PATH.test(path))
+            throw new KestrelBootError(owner, `step "${name}" declares an invalid write path "${path}"`);
+    }
+    return description;
+}
+export class StepRegistry {
+    entries = new Map();
+    register(owner, prefix, steps, descriptions = {}) {
+        for (const key of stepKeys(steps)) {
+            const value = steps[key];
+            const name = `${prefix}.${key}`;
+            if (typeof value !== "function")
+                throw new KestrelBootError(owner, `step "${name}" is not a function`);
+            const fn = value;
+            const existing = this.entries.get(name);
+            if (existing)
+                throw new KestrelBootError(owner, `step "${name}" is already registered by ${existing.owner}`);
+            const describe = descriptions[key];
+            if (describe === undefined)
+                throw new KestrelBootError(owner, `step "${name}" has no describe() entry`);
+            if (typeof describe === "function") {
+                if (!isStepFactory(fn))
+                    throw new KestrelBootError(owner, `step "${name}" takes no argument but its describe() entry is a function`);
+            }
+            else {
+                checkPaths(owner, name, describe);
+            }
+            this.entries.set(name, { owner, fn, describe });
+        }
+        for (const key of Object.keys(descriptions)) {
+            if (!(key in steps))
+                throw new KestrelBootError(owner, `describe() names step "${prefix}.${key}" which does not exist`);
+        }
+    }
+    has(name) {
+        return this.entries.has(name);
+    }
+    names() {
+        return [...this.entries.keys()];
+    }
+    resolve(spec, owner = "pipeline") {
+        const colon = spec.indexOf(":");
+        const name = colon === -1 ? spec : spec.slice(0, colon);
+        const arg = colon === -1 ? undefined : spec.slice(colon + 1);
+        const entry = this.entries.get(name);
+        if (!entry)
+            throw new KestrelBootError(owner, `unknown step "${name}"`);
+        const factory = isStepFactory(entry.fn);
+        if (arg === undefined) {
+            if (factory)
+                throw new KestrelBootError(owner, `step "${name}" requires an argument`);
+            return { name: spec, fn: entry.fn, description: entry.describe };
+        }
+        if (arg === "")
+            throw new KestrelBootError(owner, `step "${name}" has an empty argument`);
+        if (!factory)
+            throw new KestrelBootError(owner, `step "${name}" does not accept an argument`);
+        const built = entry.fn(arg);
+        if (typeof built !== "function")
+            throw new KestrelBootError(owner, `step "${name}" returned ${typeof built} instead of a step`);
+        const description = typeof entry.describe === "function" ? checkPaths(entry.owner, spec, entry.describe(arg)) : entry.describe;
+        return { name: spec, fn: built, description };
+    }
+}

package/dist/result.d.ts

@@ -0,0 +1,19 @@
+export interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface Err<E> {
+    readonly ok: false;
+    readonly error: E;
+}
+export type Result<T, E> = Ok<T> | Err<E>;
+export declare function ok(): Ok<void>;
+export declare function ok<T>(value: T): Ok<T>;
+export declare function err<E>(error: E): Err<E>;
+export declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+export declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
+export declare function match<T, E, A, B>(result: Result<T, E>, on: {
+    ok: (value: T) => A;
+    err: (error: E) => B;
+}): A | B;
+export declare function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T;

package/dist/result.js

@@ -0,0 +1,19 @@
+export function ok(value) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+    return { ok: true, value: value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+export function isOk(result) {
+    return result.ok;
+}
+export function isErr(result) {
+    return !result.ok;
+}
+export function match(result, on) {
+    return result.ok ? on.ok(result.value) : on.err(result.error);
+}
+export function unwrapOr(result, fallback) {
+    return result.ok ? result.value : fallback;
+}

package/dist/runner.d.ts

@@ -0,0 +1,29 @@
+import { type ContextInput } from "./context.ts";
+import type { Logger } from "./logger.ts";
+import type { ResolvedStep } from "./registry.ts";
+export interface ResolvedPipeline {
+    name: string;
+    steps: readonly ResolvedStep[];
+}
+export interface RunResult {
+    runId: string;
+    requestId?: string;
+    status: number;
+    result?: unknown;
+    error?: string;
+    code?: string;
+    retryable?: boolean;
+    step?: string;
+    details?: Record<string, unknown>;
+}
+export type Runner = (pipeline: string, input: ContextInput) => Promise<RunResult>;
+export interface RunOptions {
+    validateInput: boolean;
+}
+export interface RunTracker {
+    track<T>(fn: () => Promise<T>): Promise<T>;
+    active(): number;
+    drain(timeoutMs: number): Promise<boolean>;
+}
+export declare function createRunTracker(): RunTracker;
+export declare function runPipeline(pipeline: ResolvedPipeline, input: ContextInput, logger: Logger, options?: RunOptions): Promise<RunResult>;

package/dist/runner.js

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import { createContext, DONE } from "./context.js";
+import { failure, isKestrelError } from "./errors.js";
+import { isErr } from "./result.js";
+import { validateSchema } from "./schema.js";
+export function createRunTracker() {
+    let active = 0;
+    const idle = new Set();
+    return {
+        async track(fn) {
+            active++;
+            try {
+                return await fn();
+            }
+            finally {
+                active--;
+                if (active === 0)
+                    for (const resolve of [...idle])
+                        resolve();
+            }
+        },
+        active: () => active,
+        drain(timeoutMs) {
+            if (active === 0)
+                return Promise.resolve(true);
+            return new Promise((resolve) => {
+                const onIdle = () => {
+                    clearTimeout(timer);
+                    idle.delete(onIdle);
+                    resolve(true);
+                };
+                const timer = setTimeout(() => {
+                    idle.delete(onIdle);
+                    resolve(false);
+                }, Math.max(0, timeoutMs));
+                timer.unref();
+                idle.add(onIdle);
+            });
+        },
+    };
+}
+function isResult(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const result = value;
+    if (result.ok === true)
+        return "value" in result;
+    return result.ok === false && isKestrelError(result.error);
+}
+function isContext(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const ctx = value;
+    const record = (v) => typeof v === "object" && v !== null;
+    return record(ctx.trigger) && record(ctx.payload) && record(ctx.params) && record(ctx.headers) && Array.isArray(ctx.files) && typeof ctx.fail === "function" && typeof ctx.done === "function";
+}
+// Query parameters are merged into the payload by the HTTP trigger, so an `additionalProperties:
+// false` input schema has to accept them too.
+function payloadSchema(description) {
+    const input = description.input;
+    if (input === undefined)
+        return undefined;
+    if (description.query === undefined)
+        return input;
+    const properties = typeof input.properties === "object" && input.properties !== null ? input.properties : {};
+    return { ...input, properties: { ...properties, ...description.query } };
+}
+export async function runPipeline(pipeline, input, logger, options = { validateInput: false }) {
+    const runId = randomUUID();
+    let ctx = createContext(input, runId);
+    const requestId = ctx.requestId;
+    const trace = (result) => (requestId === undefined ? result : { ...result, requestId });
+    for (const step of pipeline.steps) {
+        const started = performance.now();
+        const log = (outcome) => logger.step({
+            runId,
+            ...(input.parentRunId === undefined ? {} : { parentRunId: input.parentRunId }),
+            pipeline: pipeline.name,
+            step: step.name,
+            ms: Math.round((performance.now() - started) * 100) / 100,
+            outcome,
+        });
+        if (options.validateInput) {
+            const schema = payloadSchema(step.description);
+            const problem = schema === undefined ? undefined : validateSchema(schema, ctx.payload)[0];
+            if (problem !== undefined) {
+                log("error");
+                const error = failure("INTERNAL", `dev: payload of step "${step.name}" in pipeline "${pipeline.name}" does not match describe().input at ${problem.path}: ${problem.message}`);
+                return trace({ runId, status: error.status, error: error.message, code: error.code, retryable: error.retryable, step: step.name });
+            }
+        }
+        try {
+            const out = await step.fn(ctx);
+            if (!isResult(out)) {
+                throw new Error(`step "${step.name}" returned ${typeof out} instead of a Result<Context>`);
+            }
+            if (isErr(out)) {
+                const error = out.error;
+                log(`fail(${error.code})`);
+                if (error.cause !== undefined) {
+                    const cause = error.cause instanceof Error ? { stack: error.cause.stack ?? error.cause.message } : { cause: error.cause };
+                    logger.error(`pipeline "${pipeline.name}" step "${step.name}" failed with a cause`, { runId, code: error.code, ...cause });
+                }
+                return trace({
+                    runId,
+                    status: error.status,
+                    error: error.message,
+                    code: error.code,
+                    retryable: error.retryable,
+                    step: step.name,
+                    ...(error.details === undefined ? {} : { details: error.details }),
+                });
+            }
+            if (!isContext(out.value)) {
+                throw new Error(`step "${step.name}" returned ${typeof out.value} instead of a Result<Context>`);
+            }
+            ctx = Object.freeze(out.value);
+            log("ok");
+            if (Reflect.get(ctx, DONE) === true)
+                return trace({ runId, status: 200, result: ctx.result });
+        }
+        catch (thrown) {
+            log("error");
+            const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+            logger.error(`pipeline "${pipeline.name}" step "${step.name}" threw`, { runId, stack: error.stack ?? error.message });
+            return trace({ runId, status: 500, error: `${pipeline.name}/${step.name}: ${error.message}`, code: "INTERNAL", retryable: false, step: step.name });
+        }
+    }
+    const done = { runId, status: 200 };
+    if (ctx.result !== undefined)
+        done.result = ctx.result;
+    return trace(done);
+}

package/dist/schema.d.ts

@@ -0,0 +1,7 @@
+import type { JsonSchema } from "./defineModule.ts";
+export interface SchemaProblem {
+    path: string;
+    message: string;
+}
+/** The subset of JSON Schema the shipped `describe().input` blocks use; unknown keywords are ignored. */
+export declare function validateSchema(schema: JsonSchema, value: unknown): SchemaProblem[];

package/dist/schema.js

@@ -0,0 +1,142 @@
+const ROOT = "$";
+function child(path, key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function subSchema(value) {
+    return isRecord(value) ? value : undefined;
+}
+function jsonType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function matchesType(value, type) {
+    if (type === "integer")
+        return typeof value === "number" && Number.isInteger(value);
+    if (type === "number")
+        return typeof value === "number" && Number.isFinite(value);
+    if (type === "null")
+        return value === null;
+    if (type === "array")
+        return Array.isArray(value);
+    if (type === "object")
+        return isRecord(value);
+    return jsonType(value) === type;
+}
+function typeNames(type) {
+    if (typeof type === "string")
+        return [type];
+    if (Array.isArray(type))
+        return type.filter((t) => typeof t === "string");
+    return [];
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+    if (isRecord(a) && isRecord(b)) {
+        const keys = Object.keys(a);
+        return keys.length === Object.keys(b).length && keys.every((k) => Object.hasOwn(b, k) && deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+function present(object, key) {
+    return Object.hasOwn(object, key) && object[key] !== undefined;
+}
+function check(schema, value, path, problems) {
+    const types = typeNames(schema.type);
+    if (types.length > 0 && !types.some((t) => matchesType(value, t))) {
+        problems.push({ path, message: `expected ${types.join(" or ")}, got ${jsonType(value)}` });
+        return;
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((allowed) => deepEqual(allowed, value))) {
+        problems.push({ path, message: `expected one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}` });
+    }
+    if (Object.hasOwn(schema, "const") && !deepEqual(schema.const, value)) {
+        problems.push({ path, message: `expected ${JSON.stringify(schema.const)}` });
+    }
+    if (typeof value === "string") {
+        const length = [...value].length;
+        if (typeof schema.pattern === "string" && !new RegExp(schema.pattern).test(value)) {
+            problems.push({ path, message: `does not match ${schema.pattern}` });
+        }
+        if (typeof schema.minLength === "number" && length < schema.minLength) {
+            problems.push({ path, message: `shorter than minLength ${schema.minLength}` });
+        }
+        if (typeof schema.maxLength === "number" && length > schema.maxLength) {
+            problems.push({ path, message: `longer than maxLength ${schema.maxLength}` });
+        }
+    }
+    if (typeof value === "number") {
+        if (typeof schema.minimum === "number" && value < schema.minimum)
+            problems.push({ path, message: `below minimum ${schema.minimum}` });
+        if (typeof schema.maximum === "number" && value > schema.maximum)
+            problems.push({ path, message: `above maximum ${schema.maximum}` });
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+            problems.push({ path, message: `fewer than minItems ${schema.minItems}` });
+        }
+        const items = schema.items;
+        if (Array.isArray(items)) {
+            items.forEach((item, i) => {
+                const sub = subSchema(item);
+                if (sub && i < value.length)
+                    check(sub, value[i], `${path}[${i}]`, problems);
+            });
+        }
+        else {
+            const sub = subSchema(items);
+            if (sub)
+                value.forEach((item, i) => check(sub, item, `${path}[${i}]`, problems));
+        }
+    }
+    if (isRecord(value)) {
+        const properties = isRecord(schema.properties) ? schema.properties : {};
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (typeof key === "string" && !present(value, key))
+                    problems.push({ path: child(path, key), message: "is required" });
+            }
+        }
+        for (const [key, raw] of Object.entries(properties)) {
+            const sub = subSchema(raw);
+            if (sub && present(value, key))
+                check(sub, value[key], child(path, key), problems);
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(value)) {
+                if (!Object.hasOwn(properties, key))
+                    problems.push({ path: child(path, key), message: "is not allowed by additionalProperties: false" });
+            }
+        }
+    }
+    if (Array.isArray(schema.oneOf)) {
+        const matched = schema.oneOf.filter((raw) => {
+            const sub = subSchema(raw);
+            return sub !== undefined && validateSchema(sub, value).length === 0;
+        }).length;
+        if (matched !== 1)
+            problems.push({ path, message: `matches ${String(matched)} of ${String(schema.oneOf.length)} oneOf schemas, expected exactly 1` });
+    }
+    if (Array.isArray(schema.anyOf)) {
+        const matched = schema.anyOf.some((raw) => {
+            const sub = subSchema(raw);
+            return sub !== undefined && validateSchema(sub, value).length === 0;
+        });
+        if (!matched)
+            problems.push({ path, message: `matches none of the ${String(schema.anyOf.length)} anyOf schemas` });
+    }
+}
+/** The subset of JSON Schema the shipped `describe().input` blocks use; unknown keywords are ignored. */
+export function validateSchema(schema, value) {
+    const problems = [];
+    check(schema, value, ROOT, problems);
+    return problems;
+}

package/dist/sort.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleDefinition } from "./defineModule.ts";
+export declare function sortModules(modules: readonly ModuleDefinition[]): ModuleDefinition[];

package/dist/sort.js

@@ -0,0 +1,50 @@
+import { KestrelBootError } from "./errors.js";
+export function sortModules(modules) {
+    const providerOf = new Map();
+    for (const m of modules) {
+        for (const contract of m.provides) {
+            const other = providerOf.get(contract.name);
+            if (other)
+                throw new KestrelBootError(m.name, `contract "${contract.name}" is already provided by ${other.name}`);
+            providerOf.set(contract.name, m);
+        }
+    }
+    const dependsOn = new Map();
+    for (const m of modules) {
+        const deps = [];
+        for (const contract of m.requires) {
+            const provider = providerOf.get(contract.name);
+            if (!provider)
+                throw new KestrelBootError(m.name, `requires "${contract.name}" but no active module provides it`);
+            if (provider === m)
+                throw new KestrelBootError(m.name, `requires "${contract.name}" which it provides itself`);
+            deps.push(provider);
+        }
+        for (const contract of m.optional ?? []) {
+            const provider = providerOf.get(contract.name);
+            if (!provider)
+                continue;
+            if (provider === m)
+                throw new KestrelBootError(m.name, `optional "${contract.name}" which it provides itself`);
+            deps.push(provider);
+        }
+        dependsOn.set(m, deps);
+    }
+    const sorted = [];
+    const state = new Map();
+    const visit = (m, path) => {
+        const s = state.get(m);
+        if (s === "done")
+            return;
+        if (s === "visiting")
+            throw new KestrelBootError(m.name, `dependency cycle: ${[...path, m.name].join(" -> ")}`);
+        state.set(m, "visiting");
+        for (const dep of dependsOn.get(m) ?? [])
+            visit(dep, [...path, m.name]);
+        state.set(m, "done");
+        sorted.push(m);
+    };
+    for (const m of modules)
+        visit(m, []);
+    return sorted;
+}

package/dist/testing/runPipeline.d.ts

@@ -0,0 +1,9 @@
+import type { ContextInput, Step, StepFactory } from "../context.ts";
+import type { PipelineDefinition } from "../definePipeline.ts";
+import { type Logger } from "../logger.ts";
+import { type RunResult } from "../runner.ts";
+export interface RunPipelineOptions {
+    steps: Record<string, Step | StepFactory>;
+    logger?: Logger;
+}
+export declare function runPipeline(pipeline: PipelineDefinition, input: Partial<ContextInput>, options: RunPipelineOptions): Promise<RunResult>;