@benclmnt/postmock 0.0.1

package/dist/src/control/endpoints/core.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { apiError, ERROR_FAMILIES, isSummaryRow } from "../../errors.js";
+import { formatTimestamp } from "../../time.js";
+import { ControlError, controlInput, defineControl } from "../registry.js";
+import { seedAtomically } from "../seeding.js";
+// docs/09 §5: reset, seed, clock, faults, messages.
+defineControl({
+    method: "POST",
+    path: "/control/reset",
+    handler: async (ctx) => {
+        const { seed = ctx.startupSeed } = controlInput(z.object({ seed: z.string().optional() }), ctx.body);
+        await seedAtomically(ctx, seed, { reset: true });
+        return { seed };
+    },
+});
+defineControl({
+    method: "POST",
+    path: "/control/seed",
+    handler: async (ctx) => {
+        const { name } = controlInput(z.object({ name: z.string() }), ctx.body);
+        await seedAtomically(ctx, name, { reset: false });
+        return { seed: name };
+    },
+});
+defineControl({
+    method: "POST",
+    path: "/control/clock/advance",
+    handler: async (ctx) => {
+        const { ms } = controlInput(z.object({ ms: z.int().nonnegative() }), ctx.body);
+        await ctx.clock.advance(ms);
+        return { now: formatTimestamp(ctx.clock.now(), "utc") };
+    },
+});
+const errorReply = z.object({
+    errorCode: z.int(),
+    status: z.int().optional(),
+    family: z.enum(ERROR_FAMILIES).optional(),
+    message: z.string().optional(),
+});
+const faultSchema = z.object({
+    match: z.object({ method: z.string(), path: z.string().startsWith("/") }),
+    times: z.int().positive().default(1),
+    reply: z.unknown(),
+});
+defineControl({
+    method: "POST",
+    path: "/control/faults",
+    handler: (ctx) => {
+        const { match, times, reply } = controlInput(faultSchema, ctx.body);
+        ctx.store.state.faults.push({
+            method: match.method,
+            path: match.path,
+            remaining: times,
+            reply: reply === "timeout" || reply === "reset"
+                ? reply
+                : faultError(controlInput(errorReply, reply)),
+        });
+        return { faults: ctx.store.state.faults.length };
+    },
+});
+/** Only a status and ErrorCode pair from docs/02 §4.4 can be faulted (CONTROL-API.md principle). */
+function faultError(reply) {
+    try {
+        // A message row's text is the wire text; only a summary row takes a caller message.
+        if (reply.message !== undefined && !isSummaryRow(reply.errorCode, reply.family)) {
+            throw new Error(`ErrorCode ${reply.errorCode}: message only for a summary row`);
+        }
+        const { status, body } = apiError(reply.errorCode, {
+            ...(reply.status !== undefined && { status: reply.status }),
+            ...(reply.family !== undefined && { family: reply.family }),
+            ...(reply.message !== undefined && { message: reply.message }),
+        });
+        return { status, body };
+    }
+    catch (error) {
+        throw new ControlError(error.message);
+    }
+}
+defineControl({
+    method: "GET",
+    path: "/control/messages",
+    handler: ({ store, query }) => {
+        const to = query.get("to")?.toLowerCase();
+        const tag = query.get("tag");
+        const channel = query.get("channel");
+        if (channel !== null && channel !== "rest" && channel !== "smtp") {
+            throw new ControlError(`channel must be rest or smtp, got '${channel}'`);
+        }
+        const messages = [...store.state.outbound.values()].filter((m) => (to === undefined ||
+            [...m.To, ...m.Cc, ...m.Bcc].some((a) => a.Email.toLowerCase() === to)) &&
+            (tag === null || m.Tag === tag) &&
+            (channel === null || m.channel === channel));
+        return {
+            Messages: messages.map((m) => ({
+                MessageID: m.MessageID,
+                ServerID: m.ServerID,
+                MessageStream: m.MessageStream,
+                Channel: m.channel,
+                SubmittedAt: formatTimestamp(m.ReceivedAt),
+                Request: m.request,
+            })),
+        };
+    },
+});

package/dist/src/control/endpoints/inbound.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/control/endpoints/inbound.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { receiveInbound } from "../../inbound/receive.js";
+import { composeMime } from "../../mime/compose.js";
+import { ControlError, controlInput, defineControl } from "../registry.js";
+const address = z.union([z.string(), z.object({ email: z.string(), name: z.string().optional() })]);
+const emailOf = (a) => (typeof a === "string" ? a : a.email);
+const spam = {
+    spamScore: z.number().default(0),
+    spamTests: z.array(z.string()).default([]),
+};
+const inboundSchema = z.union([
+    z.strictObject({ mime: z.string(), rcptTo: z.array(z.string()).min(1), ...spam }),
+    z.strictObject({
+        from: address,
+        to: z.array(address).default([]),
+        cc: z.array(address).default([]),
+        bcc: z.array(address).default([]),
+        replyTo: address.optional(),
+        subject: z.string().default(""),
+        text: z.string().optional(),
+        html: z.string().optional(),
+        headers: z.array(z.object({ name: z.string(), value: z.string() })).default([]),
+        attachments: z
+            .array(z.object({
+            name: z.string(),
+            content: z.base64(),
+            contentType: z.string(),
+            contentId: z.string().optional(),
+        }))
+            .default([]),
+        ...spam,
+    }),
+]);
+// Mail arrives at an inbound address (CONTROL-API.md). The body is raw MIME with its SMTP envelope,
+// or fields that postmock writes as MIME; Bcc addresses go only into the envelope.
+defineControl({
+    method: "POST",
+    path: "/control/inbound",
+    handler: async (ctx) => {
+        const input = controlInput(inboundSchema, ctx.body);
+        const mail = "mime" in input
+            ? input
+            : {
+                mime: composeMime(input, ctx.clock.now()),
+                rcptTo: [...input.to, ...input.cc, ...input.bcc].map(emailOf),
+                spamScore: input.spamScore,
+                spamTests: input.spamTests,
+            };
+        const messages = await receiveInbound(ctx, mail);
+        if (messages.length === 0) {
+            throw new ControlError(`no server has an inbound address among ${mail.rcptTo.join(", ")}`);
+        }
+        return {
+            Messages: messages.map((m) => ({
+                MessageID: m.MessageID,
+                ServerID: m.ServerID,
+                Status: m.Status,
+            })),
+        };
+    },
+});

package/dist/src/control/endpoints/recipients.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/control/endpoints/recipients.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { Unsupported } from "../../http/respond.js";
+import { recipientsOf, recordBounce, recordUnsubscribe } from "../../recipients/transitions.js";
+import { streamKey } from "../../state/store.js";
+import { ControlError, controlInput, defineControl } from "../registry.js";
+// What a recipient or its mail server does to a delivered message (docs/04 §3.2 T1–T5).
+/** Bounce types a receiving mail server reports, with a known effect on the address (docs/04 §1.4). */
+const SERVER_BOUNCE_TYPES = [
+    "HardBounce",
+    "Transient",
+    "Subscribe",
+    "AutoResponder",
+    "AddressChange",
+    "DnsError",
+    "SpamNotification",
+    "OpenRelayTest",
+    "Unknown",
+    "SoftBounce",
+    "VirusNotification",
+    "ChallengeVerification",
+];
+const target = z.object({ messageId: z.string(), recipient: z.string() });
+/** A delivered message and one of its recipients, with its case as sent. */
+function delivered(ctx, input) {
+    const message = ctx.store.state.outbound.get(input.messageId);
+    if (message === undefined)
+        throw new ControlError(`no outbound message ${input.messageId}`);
+    // A sandbox server delivers nothing, so nothing can bounce (docs/07 §2).
+    if (message.Sandboxed)
+        throw new ControlError(`message ${message.MessageID} was not delivered (sandbox)`);
+    const email = recipientsOf(message).find((r) => r.toLowerCase() === input.recipient.toLowerCase());
+    if (email === undefined) {
+        throw new ControlError(`${input.recipient} is not a recipient of ${message.MessageID}`);
+    }
+    const stream = ctx.store.state.streams.get(streamKey(message.ServerID, message.MessageStream));
+    // A purged stream, or a new stream with the same ID, never carried this message.
+    if (stream === undefined || stream.CreatedAt.getTime() > message.ReceivedAt.getTime()) {
+        throw new ControlError(`stream ${message.MessageStream} of ${message.MessageID} is gone`);
+    }
+    if (message.Status === "Queued") {
+        throw new ControlError(`message ${message.MessageID} is queued, not delivered`);
+    }
+    // A send skips an address suppressed at send time (docs/04 §3.3).
+    if (message.suppressedRecipients.some((r) => r.toLowerCase() === email.toLowerCase())) {
+        throw new ControlError(`${email} was suppressed when ${message.MessageID} was sent`);
+    }
+    return { message, email, stream };
+}
+/**
+ * One message ends once per recipient: after a bounce or complaint other than a `Transient` delay,
+ * no further bounce or complaint comes (INFERRED).
+ */
+function refuseAfterFinal(ctx, message, email) {
+    for (const bounce of ctx.store.state.bounces.values()) {
+        if (bounce.MessageID === message.MessageID &&
+            bounce.Email === email &&
+            bounce.Type !== "Transient") {
+            throw new ControlError(`${message.MessageID} already has a ${bounce.Type} for ${email}`);
+        }
+    }
+}
+/** Behavior postmock does not know is a bad control request, not a crash. */
+async function known(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof Unsupported)
+            throw new ControlError(error.message);
+        throw error;
+    }
+}
+/** A minimal DSN as the bounce dump (INFERRED shape). */
+const dsn = (message, email, details) => [
+    "Return-Path: <>",
+    "From: MAILER-DAEMON@postmock.invalid",
+    `To: ${message.From}`,
+    "Subject: Undelivered Mail Returned to Sender",
+    "Content-Type: text/plain; charset=utf-8",
+    "",
+    `Delivery to ${email} failed.`,
+    details,
+    "",
+].join("\r\n");
+defineControl({
+    method: "POST",
+    path: "/control/bounces",
+    handler: async (ctx) => {
+        const input = controlInput(target.extend({
+            type: z.enum(SERVER_BOUNCE_TYPES),
+            details: z.string().default("smtp;550 5.1.1 The email account does not exist."),
+            dump: z.string().optional(),
+        }), ctx.body);
+        const { message, email } = delivered(ctx, input);
+        refuseAfterFinal(ctx, message, email);
+        const bounce = await known(() => recordBounce(ctx, {
+            message,
+            email,
+            type: input.type,
+            details: input.details,
+            content: input.dump ?? dsn(message, email, input.details),
+        }));
+        return { ID: bounce.ID };
+    },
+});
+defineControl({
+    method: "POST",
+    path: "/control/events/spam-complaint",
+    handler: async (ctx) => {
+        const input = controlInput(target.extend({ dump: z.string().optional() }), ctx.body);
+        const { message, email } = delivered(ctx, input);
+        refuseAfterFinal(ctx, message, email);
+        const bounce = await known(() => recordBounce(ctx, {
+            message,
+            email,
+            type: "SpamComplaint",
+            details: "",
+            content: input.dump ??
+                `Content-Type: message/feedback-report\r\n\r\nFeedback-Type: abuse\r\nOriginal-Rcpt-To: ${email}\r\n`,
+        }));
+        return { ID: bounce.ID };
+    },
+});
+defineControl({
+    method: "POST",
+    path: "/control/events/unsubscribe",
+    handler: async (ctx) => {
+        const { message, email, stream } = delivered(ctx, controlInput(target, ctx.body));
+        // Postmark adds its unsubscribe link only on such a stream (docs/04 §3.2 T5).
+        if (stream.MessageStreamType !== "Broadcasts" ||
+            stream.SubscriptionManagementConfiguration.UnsubscribeHandlingType !== "Postmark") {
+            throw new ControlError(`stream ${message.MessageStream} has no Postmark unsubscribe handling`);
+        }
+        return { suppressed: await known(() => recordUnsubscribe(ctx, message, email)) };
+    },
+});

package/dist/src/control/endpoints/smtp.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/control/endpoints/smtp.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { newHex } from "../../state/ids.js";
+import { streamKey } from "../../state/store.js";
+import { ControlError, controlInput, defineControl } from "../registry.js";
+// docs/07 Mock must: tests create and revoke SMTP tokens, and fault the SMTP session.
+defineControl({
+    method: "POST",
+    path: "/control/smtp/tokens",
+    handler: ({ store, body }) => {
+        const input = controlInput(z.object({ serverId: z.int(), messageStream: z.string() }), body);
+        const server = store.state.servers.get(input.serverId);
+        if (server === undefined)
+            throw new ControlError(`no server ${input.serverId}`);
+        const stream = store.state.streams.get(streamKey(server.ID, input.messageStream));
+        if (stream === undefined) {
+            throw new ControlError(`server ${server.ID} has no stream '${input.messageStream}'`);
+        }
+        // The UI refuses these like ErrorCodes 1457, 1459 and 1460 (refs/api_overview.md:191-194).
+        if (stream.MessageStreamType === "Inbound") {
+            throw new ControlError("Tokens cannot be used with inbound streams.");
+        }
+        if (stream.ArchivedAt !== null) {
+            throw new ControlError("A token cannot be issued for an archived stream scheduled for deletion.");
+        }
+        if (!server.SmtpApiActivated) {
+            throw new ControlError("SMTP is currently disabled for the specified server.");
+        }
+        // Key formats are not documented (docs/07 Q16): INFERRED.
+        const token = {
+            accessKey: newHex(16),
+            secretKey: newHex(32),
+            serverId: server.ID,
+            messageStream: stream.ID,
+        };
+        store.state.smtpTokens.set(token.accessKey, token);
+        return {
+            AccessKey: token.accessKey,
+            SecretKey: token.secretKey,
+            ServerID: token.serverId,
+            MessageStream: token.messageStream,
+        };
+    },
+});
+defineControl({
+    method: "DELETE",
+    path: "/control/smtp/tokens/:accessKey",
+    handler: ({ store, params }) => {
+        const accessKey = params.accessKey;
+        if (!store.state.smtpTokens.delete(accessKey)) {
+            throw new ControlError(`no SMTP token '${accessKey}'`);
+        }
+        return { AccessKey: accessKey };
+    },
+});
+const faultSchema = z.object({
+    stage: z.enum(["connect", "mail", "rcpt", "data"]),
+    times: z.int().positive().default(1),
+    // A 4xx or 5xx reply; 421 also closes the connection (an outage or an idle close).
+    reply: z.object({ code: z.int().min(400).max(599), message: z.string().min(1) }),
+});
+defineControl({
+    method: "POST",
+    path: "/control/smtp/faults",
+    handler: ({ store, body }) => {
+        const { stage, times, reply } = controlInput(faultSchema, body);
+        store.state.smtpFaults.push({
+            stage,
+            remaining: times,
+            code: reply.code,
+            message: reply.message,
+        });
+        return { faults: store.state.smtpFaults.length };
+    },
+});

package/dist/src/control/endpoints/tracking.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/control/endpoints/tracking.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { formatTimestamp } from "../../time.js";
+import { recordClick, recordDelivery, recordOpen, TrackingRefused, } from "../../tracking.js";
+import { ControlError, controlInput, defineControl } from "../registry.js";
+// Recipient actions on a sent message (CONTROL-API.md): delivery, open, click. Each fires the same
+// event a real recipient action fires, so webhooks, message events and stats follow.
+const clientInfo = z.object({ name: z.string(), company: z.string(), family: z.string() });
+const agentSchema = {
+    // Postmark reads the client from the user agent. The mock takes the parsed parts from the test.
+    userAgent: z.string().min(1).default("Mozilla/5.0 (postmock)"),
+    client: clientInfo.optional(),
+    os: clientInfo.optional(),
+    platform: z.enum(["WebMail", "Desktop", "Mobile", "Unknown"]).optional(),
+    geo: z
+        .object({
+        countryISOCode: z.string(),
+        country: z.string(),
+        regionISOCode: z.string(),
+        region: z.string(),
+        city: z.string(),
+        zip: z.string(),
+        coords: z.string(),
+        ip: z.string(),
+    })
+        .partial()
+        .refine((geo) => Object.keys(geo).length > 0, "geo needs at least one field")
+        .optional(),
+};
+const target = { messageId: z.string(), recipient: z.string() };
+const info = (c) => c === undefined ? null : { Name: c.name, Company: c.company, Family: c.family };
+const agent = (input) => ({
+    UserAgent: input.userAgent,
+    Client: info(input.client),
+    OS: info(input.os),
+    Platform: input.platform ?? null,
+    Geo: input.geo === undefined
+        ? null
+        : Object.fromEntries(Object.entries({
+            CountryISOCode: input.geo.countryISOCode,
+            Country: input.geo.country,
+            RegionISOCode: input.geo.regionISOCode,
+            Region: input.geo.region,
+            City: input.geo.city,
+            Zip: input.geo.zip,
+            Coords: input.geo.coords,
+            IP: input.geo.ip,
+        }).filter(([, v]) => v !== undefined)),
+});
+const refusedAs400 = async (record) => {
+    try {
+        return await record();
+    }
+    catch (error) {
+        if (error instanceof TrackingRefused)
+            throw new ControlError(error.message);
+        throw error;
+    }
+};
+const eventReply = (e) => ({
+    MessageID: e.MessageID,
+    Recipient: e.Recipient,
+    ReceivedAt: formatTimestamp(e.ReceivedAt),
+});
+defineControl({
+    method: "POST",
+    path: "/control/events/delivery",
+    handler: async (ctx) => {
+        const input = controlInput(z.object({ ...target, details: z.string().default("smtp;250 2.0.0 OK") }), ctx.body);
+        const delivery = await refusedAs400(() => recordDelivery(ctx, input));
+        return eventReply(delivery);
+    },
+});
+defineControl({
+    method: "POST",
+    path: "/control/events/open",
+    handler: async (ctx) => {
+        const input = controlInput(z.object({ ...target, ...agentSchema, readSeconds: z.int().nonnegative().default(0) }), ctx.body);
+        const open = await refusedAs400(() => recordOpen(ctx, { ...input, agent: agent(input) }));
+        return { ...eventReply(open), FirstOpen: open.FirstOpen };
+    },
+});
+defineControl({
+    method: "POST",
+    path: "/control/events/click",
+    handler: async (ctx) => {
+        const input = controlInput(z.object({
+            ...target,
+            ...agentSchema,
+            link: z.string(),
+            clickLocation: z.enum(["HTML", "Text"]),
+        }), ctx.body);
+        const click = await refusedAs400(() => recordClick(ctx, { ...input, location: input.clickLocation, agent: agent(input) }));
+        return eventReply(click);
+    },
+});

package/dist/src/control/endpoints/webhooks.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/control/endpoints/webhooks.js

@@ -0,0 +1,36 @@
+import { formatTimestamp } from "../../time.js";
+import { ControlError, defineControl } from "../registry.js";
+// The webhook delivery log (docs/05 §6): one row per POST attempt, oldest first.
+defineControl({
+    method: "GET",
+    path: "/control/webhooks/attempts",
+    handler: ({ store, query }) => {
+        const int = (name) => {
+            const value = query.get(name);
+            if (value !== null && !/^\d+$/.test(value))
+                throw new ControlError(`${name} must be an integer`);
+            return value === null ? null : Number(value);
+        };
+        const [serverId, webhookId] = [int("serverId"), int("webhookId")];
+        const recordType = query.get("recordType");
+        const rows = store.state.webhookAttempts.filter((a) => (serverId === null || a.serverId === serverId) &&
+            (webhookId === null || a.webhookId === webhookId) &&
+            (recordType === null || a.recordType === recordType));
+        return {
+            Attempts: rows.map((a) => ({
+                ServerID: a.serverId,
+                WebhookID: a.webhookId,
+                RecordType: a.recordType,
+                Url: a.url,
+                TraceID: a.traceId,
+                Attempt: a.attempt,
+                At: formatTimestamp(a.at, "utc"),
+                Headers: a.headers,
+                Body: JSON.parse(a.body),
+                ...("status" in a.outcome ? { HttpStatus: a.outcome.status } : { Error: a.outcome.error }),
+                Result: a.result,
+                NextAttemptAt: a.nextAttemptAt === null ? null : formatTimestamp(a.nextAttemptAt, "utc"),
+            })),
+        };
+    },
+});

package/dist/src/control/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/control/index.js

@@ -0,0 +1,3 @@
+import { importAll } from "../discover.js";
+// Loads every `src/control/endpoints/*.ts`; each registers its endpoints with `defineControl`.
+await importAll(new URL("./endpoints/", import.meta.url));

package/dist/src/control/registry.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { type Method, RouteTable } from "../http/routes.ts";
+import type { Runtime } from "../runtime.ts";
+/** A control request the test got wrong. Answers 400 `{"error": "..."}` (CONTROL-API.md). */
+export declare class ControlError extends Error {
+}
+export interface ControlContext extends Runtime {
+    params: Record<string, string>;
+    query: URLSearchParams;
+    /** Parsed JSON body; `undefined` when empty. */
+    body: unknown;
+    /** The seed postmock started with; `POST /control/reset` applies it again. */
+    startupSeed: string;
+}
+export interface ControlRoute {
+    method: Method;
+    path: string;
+    /** Returns the JSON body of a 200 response. */
+    handler: (ctx: ControlContext) => unknown;
+}
+export declare const controlRoutes: RouteTable<ControlRoute>;
+/** Registers a control endpoint under `/control`. Each `src/control/<topic>.ts` calls it at import. */
+export declare function defineControl(route: ControlRoute): void;
+/** Parses a control body with zod; a failure is a `ControlError` naming the fields. */
+export declare function controlInput<S extends z.ZodType>(schema: S, value: unknown): z.output<S>;

package/dist/src/control/registry.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { RouteTable } from "../http/routes.js";
+/** A control request the test got wrong. Answers 400 `{"error": "..."}` (CONTROL-API.md). */
+export class ControlError extends Error {
+}
+export const controlRoutes = new RouteTable();
+/** Registers a control endpoint under `/control`. Each `src/control/<topic>.ts` calls it at import. */
+export function defineControl(route) {
+    if (!route.path.startsWith("/control/"))
+        throw new Error(`control path ${route.path}`);
+    controlRoutes.add(route);
+}
+/** Parses a control body with zod; a failure is a `ControlError` naming the fields. */
+export function controlInput(schema, value) {
+    const result = schema.safeParse(value ?? {});
+    if (!result.success)
+        throw new ControlError(z.prettifyError(result.error));
+    return result.data;
+}

package/dist/src/control/seed.d.ts

@@ -0,0 +1,11 @@
+import type { Runtime } from "../runtime.ts";
+/** A seed builds state that real Postmark could hold, directly in the store (CONTROL-API.md). */
+export type Seed = (runtime: Runtime) => void | Promise<void>;
+/**
+ * A seed made of every part file in `dir`, applied in filename order. Each track adds its own part
+ * file (docs/11 §5). A part uses fixed IDs (`store.useId`), so its IDs do not depend on other parts.
+ */
+export declare const seedFromDirectory: (dir: URL) => Seed;
+export declare const seedNames: () => string[];
+/** Loads `seeds/<name>.ts` (`.js` in the package) and applies its default export. */
+export declare function applySeed(runtime: Runtime, name: string): Promise<void>;

package/dist/src/control/seed.js

@@ -0,0 +1,32 @@
+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 { existsSync, readdirSync } from "node:fs";
+import { defaultFunction, importAll, MODULE_EXTENSION } from "../discover.js";
+const SEEDS_DIR = new URL("../../seeds/", import.meta.url);
+/**
+ * A seed made of every part file in `dir`, applied in filename order. Each track adds its own part
+ * file (docs/11 §5). A part uses fixed IDs (`store.useId`), so its IDs do not depend on other parts.
+ */
+export const seedFromDirectory = (dir) => async (runtime) => {
+    for (const part of await importAll(dir))
+        await defaultFunction(part)(runtime);
+};
+export const seedNames = () => readdirSync(SEEDS_DIR)
+    .filter((f) => f.endsWith(MODULE_EXTENSION) && !f.endsWith(`.test${MODULE_EXTENSION}`))
+    .map((f) => f.slice(0, -MODULE_EXTENSION.length))
+    .sort();
+/** Loads `seeds/<name>.ts` (`.js` in the package) and applies its default export. */
+export async function applySeed(runtime, name) {
+    const file = new URL(`${name}${MODULE_EXTENSION}`, SEEDS_DIR);
+    if (!/^[a-z0-9-]+$/.test(name) || !existsSync(file)) {
+        throw new Error(`unknown seed '${name}'; seeds: ${seedNames().join(", ")}`);
+    }
+    const seed = defaultFunction({ url: file, module: await import(__rewriteRelativeImportExtension(file.href)) });
+    await runtime.store.seeding(async () => seed(runtime));
+}

package/dist/src/control/seeding.d.ts

@@ -0,0 +1,10 @@
+import type { Runtime } from "../runtime.ts";
+import { applySeed } from "./seed.ts";
+/**
+ * Applies a seed, after a full reset when `reset` is set, or changes nothing: a failing seed
+ * restores the state, the clock offset and the pending clock tasks, and answers 400.
+ * The clock resets before the seed, so seeded dates and seed-scheduled tasks use the fresh clock.
+ */
+export declare function seedAtomically(runtime: Runtime, name: string, { reset }: {
+    reset: boolean;
+}, apply?: typeof applySeed): Promise<void>;

package/dist/src/control/seeding.js

@@ -0,0 +1,27 @@
+import { ControlError } from "./registry.js";
+import { applySeed, seedNames } from "./seed.js";
+/**
+ * Applies a seed, after a full reset when `reset` is set, or changes nothing: a failing seed
+ * restores the state, the clock offset and the pending clock tasks, and answers 400.
+ * The clock resets before the seed, so seeded dates and seed-scheduled tasks use the fresh clock.
+ */
+export async function seedAtomically(runtime, name, { reset }, apply = applySeed) {
+    if (!seedNames().includes(name)) {
+        throw new ControlError(`unknown seed '${name}'; seeds: ${seedNames().join(", ")}`);
+    }
+    await runtime.clock.idle();
+    const state = structuredClone(runtime.store.state);
+    const restoreClock = runtime.clock.checkpoint();
+    try {
+        if (reset) {
+            runtime.store.reset();
+            runtime.clock.reset();
+        }
+        await apply(runtime, name);
+    }
+    catch (error) {
+        runtime.store.state = state;
+        restoreClock();
+        throw new ControlError(`seed '${name}' failed: ${error.message}`);
+    }
+}