@astralarium/repo-dev 0.0.0-stage → 0.1.0

package/dist/launcher/servers.js

@@ -0,0 +1,154 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { Agent, fetch } from "undici";
+import { z } from "zod";
+import { PORT } from "../config.js";
+import { appProcessEnv } from "../environment.js";
+import { output } from "../exec.js";
+import { isPortOpen, waitFor, waitForPortClose } from "../wait.js";
+/** `<stateDir>/<name>.json`: the live session a launch started, its config
+ *  hash and the ports it started on. */
+const sessionState = z.object({
+    id: z.string(),
+    fingerprint: z.string(),
+    port: PORT,
+    inspectorPort: PORT.optional(),
+});
+/** Hashes the effective app config and the contents of `files`; stores no
+ *  credential values. */
+export function configFingerprint(env, files = []) {
+    const hash = createHash("sha256").update(JSON.stringify(Object.entries(env).sort(([a], [b]) => a.localeCompare(b))));
+    for (const file of files)
+        hash.update(readFileSync(file));
+    return hash.digest("hex");
+}
+/** Running session `name`, scoped to `appDir`, where `live run -C` put it. */
+export function runningSession(name, appDir) {
+    const lines = output("live", ["ps", "--json", "-C", appDir, name]);
+    if (!lines)
+        return undefined;
+    const session = JSON.parse(lines.split("\n")[0]);
+    if (!session ||
+        typeof session !== "object" ||
+        !("id" in session) ||
+        typeof session.id !== "string")
+        throw new Error(`Invalid live session: ${name}`);
+    return { id: session.id };
+}
+/** Session state from a previous launch; unreadable content counts as none
+ *  and forces a restart. */
+function savedSession(path) {
+    try {
+        const result = sessionState.safeParse(JSON.parse(readFileSync(path, "utf8")));
+        return result.success ? result.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Ports session `id` of `name` started on, per its state in `stateDir`;
+ *  undefined when the state records another session. */
+export function sessionPorts(stateDir, name, id) {
+    const saved = savedSession(resolve(stateDir, `${name}.json`));
+    if (saved?.id !== id)
+        return undefined;
+    return {
+        port: saved.port,
+        ...(saved.inspectorPort !== undefined && {
+            inspectorPort: saved.inspectorPort,
+        }),
+    };
+}
+/** Stops session `id` of `name`, then waits for each of its ports to close. */
+export async function stopSession(name, id, { port, inspectorPort }, signal) {
+    execFileSync("live", ["stop", id], { stdio: "inherit" });
+    await Promise.all([port, inspectorPort].flatMap((held) => held === undefined
+        ? []
+        : [
+            waitForPortClose(held, `${name}: :${held} still held after stopping`, signal),
+        ]));
+}
+/** HTTP readiness through the actual listener, including TLS and optional body checks. */
+export async function httpReady(url, agent, options = {}) {
+    try {
+        const response = await fetch(url, {
+            dispatcher: agent,
+            redirect: "manual",
+            signal: AbortSignal.any([
+                AbortSignal.timeout(10_000),
+                ...(options.signal ? [options.signal] : []),
+            ]),
+        });
+        const body = await response.text();
+        return (response.status === (options.status ?? 200) &&
+            (options.body === undefined || body === options.body));
+    }
+    catch {
+        return false;
+    }
+}
+/** Starts or reconciles one dev service; rollback owns only the new session. */
+export async function startDevServer(resources, options) {
+    const { name, appDir, stateDir, port, inspectorPort, env, inputs, probe } = options;
+    resources.signal.throwIfAborted();
+    if (existsSync(resolve(appDir, ".dev.vars")))
+        throw new ExpectedError(`${appDir}/.dev.vars exists; remove it, the launcher supplies the dev config`);
+    const fingerprint = configFingerprint(env, inputs);
+    const statePath = resolve(stateDir, `${name}.json`);
+    const current = runningSession(name, appDir);
+    const saved = savedSession(statePath);
+    const reused = current !== undefined &&
+        saved?.id === current.id &&
+        saved.fingerprint === fingerprint;
+    const ports = [port, ...(inspectorPort === undefined ? [] : [inspectorPort])];
+    let id;
+    if (reused) {
+        id = current.id;
+    }
+    else {
+        if (current) {
+            log.info("dev.server_restarting", "{name}: config changed; restarting", { name });
+            await stopSession(name, current.id, { port, inspectorPort }, resources.signal);
+        }
+        for (const held of ports)
+            if (await isPortOpen(held, "localhost"))
+                throw new ExpectedError(`:${held} is held by another process; ${name} cannot start`);
+        resources.signal.throwIfAborted();
+        id = execFileSync("live", ["run", "-dn", name, "-C", appDir, "pnpm", "dev", "--port", String(port)], {
+            encoding: "utf8",
+            env: appProcessEnv(env, {
+                mode: "dev",
+                nodeOptions: "--unhandled-rejections=warn",
+            }),
+        }).trim();
+        const started = id;
+        resources.own({
+            dispose: () => {
+                execFileSync("live", ["stop", started], { stdio: "inherit" });
+            },
+        });
+    }
+    const agent = new Agent({ connect: { ca: options.ca } });
+    try {
+        await waitFor(async () => {
+            if (runningSession(name, appDir)?.id !== id)
+                throw new ExpectedError(`${name} exited during startup. Inspect: live tail ${id}`);
+            return probe(agent);
+        }, `${name} failed HTTP readiness after 60s. Inspect: live tail ${id}`, 60_000, resources.signal);
+    }
+    finally {
+        await agent.close();
+    }
+    mkdirSync(stateDir, { recursive: true });
+    const state = {
+        id,
+        fingerprint,
+        port,
+        ...(inspectorPort !== undefined && { inspectorPort }),
+    };
+    writeFileSync(statePath, JSON.stringify(state), { mode: 0o600 });
+    log.info("dev.server_ready", "{name}: HTTP ready on :{port}{reused, select, true { (reused)} other {}}", { name, port, reused });
+}

package/dist/load-config.d.ts

@@ -0,0 +1,3 @@
+import { type DevConfig } from "./config.ts";
+/** The app module's `dev` config at `path`, validated (`defineDevConfig`). */
+export declare function loadDevConfig(path: string): Promise<DevConfig>;

package/dist/load-config.js

@@ -0,0 +1,6 @@
+import { loadApp } from "@astralarium/repo-deploy-info/server";
+import { defineDevConfig } from "./config.js";
+/** The app module's `dev` config at `path`, validated (`defineDevConfig`). */
+export async function loadDevConfig(path) {
+    return loadApp(path, "dev", (value) => defineDevConfig(value));
+}

package/dist/ports.d.ts

@@ -0,0 +1,3 @@
+/** `saved` while free and outside `taken` (ports this allocation already
+ *  holds), else the first free port from `preferred`. */
+export declare function keepOrFindPort(saved: number | undefined, preferred: number, taken?: ReadonlySet<number>): Promise<number>;

package/dist/ports.js

@@ -0,0 +1,32 @@
+/** Dev server ports: free-port search from a preferred port. */
+import { createServer } from "node:net";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { isPortOpen } from "./wait.js";
+/** Ports tried above the preferred one before giving up. */
+const PORT_RANGE = 100;
+/** Both loopback addresses refuse connections and a loopback bind
+ *  succeeds. */
+async function isPortFree(port) {
+    if ((await isPortOpen(port, "127.0.0.1")) || (await isPortOpen(port, "::1")))
+        return false;
+    return new Promise((done) => {
+        const server = createServer();
+        server.once("error", () => done(false));
+        server.listen({ port, host: "127.0.0.1", exclusive: true }, () => server.close(() => done(true)));
+    });
+}
+/** First free port from `preferred` upward, outside `taken`; throws
+ *  `ExpectedError` past `PORT_RANGE` ports. */
+async function findFreePort(preferred, taken) {
+    for (let port = preferred; port < preferred + PORT_RANGE; port++)
+        if (!taken.has(port) && (await isPortFree(port)))
+            return port;
+    throw new ExpectedError(`no free port in ${preferred}-${preferred + PORT_RANGE - 1}`);
+}
+/** `saved` while free and outside `taken` (ports this allocation already
+ *  holds), else the first free port from `preferred`. */
+export async function keepOrFindPort(saved, preferred, taken = new Set()) {
+    return saved !== undefined && !taken.has(saved) && (await isPortFree(saved))
+        ? saved
+        : findFreePort(preferred, taken);
+}

package/dist/process.d.ts

@@ -0,0 +1,43 @@
+/** Forked children with IPC readiness: the parent side and the child side. */
+import { type ForkOptions } from "node:child_process";
+import type { Resource } from "./resources.ts";
+/** Exit status for an interrupted child operation. */
+export declare const STOP_EXIT_CODE = 130;
+/** Runs the child cleanup once when its parent stops or disconnects. */
+export declare function onParentStop(stop: () => void): () => void;
+/** A service a child process runs for its parent. */
+export interface ChildService {
+    /** Value the child reports to its parent once the service is up. */
+    ready: unknown;
+    /** Brings the service down; runs once. */
+    stop(): void | Promise<void>;
+    /** The service completes at readiness: the child stops and disconnects
+     *  right after reporting. */
+    oneShot?: boolean;
+}
+/**
+ * Runs `name` as the child side of `forkProcess`: `start` brings the
+ * service up and its ready value reports to the parent; the service stops
+ * once, on parent stop, a failure or (`oneShot`) the report, and the child
+ * disconnects after it. `start`'s signal aborts on parent stop or, with a
+ * readiness timeout as its reason, when the startup budget runs out; a
+ * half-started service closes itself on abort. A failure logs under
+ * `child.failed`, a stop failure under `child.stop_failed`; both set the
+ * exit code.
+ */
+export declare function serveChild(name: string, start: (signal: AbortSignal) => Promise<ChildService>): void;
+/** Child process with IPC readiness and bounded graceful shutdown. */
+export interface ProcessResource extends Resource {
+    /** The child's first IPC message; rejects on an earlier exit, abort or
+     *  `READY_TIMEOUT_MS`. */
+    ready: Promise<unknown>;
+    /** Settles at exit: resolves on status 0 or a stop this side requested. */
+    exited: Promise<void>;
+}
+/**
+ * Forks a child; the first IPC message declares readiness, `close` requests
+ * shutdown. The child's env carries the readiness deadline `serveChild`
+ * budgets startup against. A stop this side initiated counts as a clean
+ * exit, including the SIGKILL sent after the 10s grace period.
+ */
+export declare function forkProcess(module: URL, args: string[], options: ForkOptions, signal: AbortSignal): ProcessResource;

package/dist/process.js

@@ -0,0 +1,172 @@
+/** Forked children with IPC readiness: the parent side and the child side. */
+import { fork } from "node:child_process";
+import { once } from "node:events";
+import { log } from "@astralarium/repo-telemetry";
+import { READY_TIMEOUT_MS } from "./wait.js";
+/** Exit status for an interrupted child operation. */
+export const STOP_EXIT_CODE = 130;
+const STOP_MESSAGE = "close";
+/** Child env var: the parent's readiness deadline, epoch milliseconds. */
+const READY_DEADLINE_ENV = "CHILD_READY_DEADLINE";
+/** Time a child keeps before its parent's deadline to fail, close and exit. */
+const STOP_MARGIN_MS = 5_000;
+/** Runs the child cleanup once when its parent stops or disconnects. */
+export function onParentStop(stop) {
+    let stopped = false;
+    const run = () => {
+        if (!stopped) {
+            stopped = true;
+            stop();
+        }
+    };
+    const onMessage = (message) => {
+        if (message === STOP_MESSAGE)
+            run();
+    };
+    process.once("SIGTERM", run);
+    process.once("disconnect", run);
+    process.on("message", onMessage);
+    return () => {
+        process.off("SIGTERM", run);
+        process.off("disconnect", run);
+        process.off("message", onMessage);
+    };
+}
+/** Reports a child's ready value over its parent's IPC channel. */
+function reportReady(value) {
+    if (!process.connected)
+        throw new Error("Parent disconnected before readiness");
+    process.send(value);
+}
+/**
+ * Startup budget of a `serveChild` child: the parent's readiness deadline
+ * minus `STOP_MARGIN_MS`, so a child timeout reports before the parent's.
+ * `READY_TIMEOUT_MS` without a parent deadline.
+ */
+function startupBudget() {
+    const deadline = Number(process.env[READY_DEADLINE_ENV]);
+    return Number.isFinite(deadline)
+        ? Math.max(0, deadline - Date.now() - STOP_MARGIN_MS)
+        : READY_TIMEOUT_MS;
+}
+/**
+ * Runs `name` as the child side of `forkProcess`: `start` brings the
+ * service up and its ready value reports to the parent; the service stops
+ * once, on parent stop, a failure or (`oneShot`) the report, and the child
+ * disconnects after it. `start`'s signal aborts on parent stop or, with a
+ * readiness timeout as its reason, when the startup budget runs out; a
+ * half-started service closes itself on abort. A failure logs under
+ * `child.failed`, a stop failure under `child.stop_failed`; both set the
+ * exit code.
+ */
+export function serveChild(name, start) {
+    const parentStop = new AbortController();
+    const timeout = new AbortController();
+    const budget = startupBudget();
+    const timer = setTimeout(() => timeout.abort(new Error(`${name} did not become ready in ${Math.round(budget / 1000)}s`)), budget);
+    const started = start(AbortSignal.any([parentStop.signal, timeout.signal]));
+    void started.then(() => clearTimeout(timer), () => clearTimeout(timer));
+    let stopping;
+    const stop = () => (stopping ??= started
+        .then((service) => service.stop(), () => undefined)
+        .catch((error) => {
+        log.error("child.stop_failed", "{name} failed to stop", { name, exception: error });
+        process.exitCode = 1;
+    })
+        .finally(() => {
+        if (process.connected)
+            process.disconnect?.();
+    }));
+    onParentStop(() => {
+        parentStop.abort();
+        void stop();
+    });
+    void started
+        .then((service) => {
+        if (stopping || !process.connected)
+            return stop();
+        reportReady(service.ready);
+        if (service.oneShot)
+            return stop();
+    })
+        .catch((error) => {
+        if (!parentStop.signal.aborted) {
+            log.error("child.failed", "{name} failed", {
+                name,
+                exception: error,
+            });
+            process.exitCode = 1;
+        }
+        return stop();
+    });
+}
+/**
+ * Forks a child; the first IPC message declares readiness, `close` requests
+ * shutdown. The child's env carries the readiness deadline `serveChild`
+ * budgets startup against. A stop this side initiated counts as a clean
+ * exit, including the SIGKILL sent after the 10s grace period.
+ */
+export function forkProcess(module, args, options, signal) {
+    signal.throwIfAborted();
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    const child = fork(module, args, {
+        execArgv: [],
+        stdio: ["ignore", "inherit", "inherit", "ipc"],
+        ...options,
+        env: {
+            ...(options.env ?? process.env),
+            [READY_DEADLINE_ENV]: String(deadline),
+        },
+    });
+    let stopping = false;
+    let ended = false;
+    const exited = new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", (code, exitSignal) => {
+            ended = true;
+            if (code === 0 ||
+                (stopping &&
+                    (exitSignal === "SIGTERM" ||
+                        exitSignal === "SIGKILL" ||
+                        code === STOP_EXIT_CODE)))
+                resolve();
+            else
+                reject(new Error(`Child ${args.join(" ")} exited (${exitSignal ?? code})`));
+        });
+    });
+    const ready = Promise.race([
+        once(child, "message", {
+            signal: AbortSignal.any([signal, AbortSignal.timeout(READY_TIMEOUT_MS)]),
+        }).then(([message]) => message),
+        exited.then(() => {
+            throw new Error("Child exited before readiness");
+        }),
+    ]);
+    // Either promise may settle unobserved.
+    void ready.catch(() => undefined);
+    void exited.catch(() => undefined);
+    let closing;
+    return {
+        ready,
+        exited,
+        dispose: () => (closing ??= (async () => {
+            if (ended)
+                return;
+            stopping = true;
+            if (child.connected)
+                child.send(STOP_MESSAGE, (error) => {
+                    if (error)
+                        child.kill("SIGTERM");
+                });
+            else
+                child.kill("SIGTERM");
+            const timeout = setTimeout(() => child.kill("SIGKILL"), 10_000);
+            try {
+                await exited;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        })()),
+    };
+}

package/dist/resources.d.ts

@@ -0,0 +1,23 @@
+/** Owned resource released by its startup caller. */
+export interface Resource {
+    dispose(): void | Promise<void>;
+}
+/** Cancellable ownership: reverse-order cleanup on an `AsyncDisposableStack`. */
+export declare class ResourceScope {
+    #private;
+    /** Cancellation shared by acquisition and readiness checks; its reason
+     *  is an `ExpectedError`. */
+    get signal(): AbortSignal;
+    /** Registers a resource before awaiting its readiness. */
+    own<T extends Resource>(resource: T): T;
+    /** Releases owned resources on SIGINT/SIGTERM while keeping normal teardown explicit. */
+    listenForSignals(): void;
+    /** Transfers successful detached dev services to the user. */
+    release(): void;
+    /** Idempotent cleanup; every resource runs even when another fails. */
+    dispose(): Promise<void>;
+}
+/** Owns setup resources until the returned teardown, including failed
+ *  setup. Setup failing after the scope closed rejects with the close
+ *  reason. */
+export declare function setupResources(setup: (resources: ResourceScope) => Promise<void>): Promise<() => Promise<void>>;

package/dist/resources.js

@@ -0,0 +1,74 @@
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+/** Cancellable ownership: reverse-order cleanup on an `AsyncDisposableStack`. */
+export class ResourceScope {
+    #controller = new AbortController();
+    #stack = new AsyncDisposableStack();
+    #closing;
+    #unlisten;
+    /** Cancellation shared by acquisition and readiness checks; its reason
+     *  is an `ExpectedError`. */
+    get signal() {
+        return this.#controller.signal;
+    }
+    /** Registers a resource before awaiting its readiness. */
+    own(resource) {
+        this.signal.throwIfAborted();
+        return this.#stack.adopt(resource, (owned) => owned.dispose());
+    }
+    /** Releases owned resources on SIGINT/SIGTERM while keeping normal teardown explicit. */
+    listenForSignals() {
+        if (this.#unlisten)
+            return;
+        const stop = (signal) => {
+            process.exitCode = signal === "SIGINT" ? 130 : 143;
+            void this.dispose().catch((e) => {
+                log.error("dev.dispose_failed", "dispose failed", { exception: e });
+            });
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+        this.#unlisten = () => {
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+        };
+    }
+    /** Transfers successful detached dev services to the user. */
+    release() {
+        this.signal.throwIfAborted();
+        this.#unlisten?.();
+        this.#stack.move();
+    }
+    /** Idempotent cleanup; every resource runs even when another fails. */
+    dispose() {
+        return (this.#closing ??= this.#dispose());
+    }
+    async #dispose() {
+        this.#controller.abort(new ExpectedError("Resource scope closed"));
+        this.#unlisten?.();
+        await this.#stack.disposeAsync();
+    }
+}
+/** Owns setup resources until the returned teardown, including failed
+ *  setup. Setup failing after the scope closed rejects with the close
+ *  reason. */
+export async function setupResources(setup) {
+    const resources = new ResourceScope();
+    resources.listenForSignals();
+    try {
+        await setup(resources);
+        resources.signal.throwIfAborted();
+        return () => resources.dispose();
+    }
+    catch (error) {
+        const failure = resources.signal.aborted
+            ? resources.signal.reason
+            : error;
+        try {
+            await resources.dispose();
+        }
+        catch (cleanup) {
+            throw new SuppressedError(cleanup, failure, "Setup and cleanup failed");
+        }
+        throw failure;
+    }
+}

package/dist/sibling-inputs.d.ts

@@ -0,0 +1,5 @@
+import type { SiblingCheckout } from "@astralarium/repo-deploy-info/server";
+/** Writes package-local fingerprints (`.turbo/siblings.json`) of each
+ *  consumed sibling, keyed by `package`; `null` for siblings a package
+ *  leaves unread. */
+export declare function writeSiblingInputs(workspace: string, siblings: readonly SiblingCheckout[]): void;

package/dist/sibling-inputs.js

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEPENDENCY_FIELDS, workspacePackages, } from "@astralarium/repo-package-files";
+import { sourceHash } from "./source-hash.js";
+/** Fingerprint of a missing checkout. */
+const ABSENT = "absent";
+/** Writes package-local fingerprints (`.turbo/siblings.json`) of each
+ *  consumed sibling, keyed by `package`; `null` for siblings a package
+ *  leaves unread. */
+export function writeSiblingInputs(workspace, siblings) {
+    const hashes = new Map();
+    for (const { dir, manifest } of workspacePackages(workspace)) {
+        const fingerprints = Object.fromEntries(siblings.map((sibling) => {
+            const consumed = sibling.consumes
+                ? sibling.consumes({ dir, manifest })
+                : DEPENDENCY_FIELDS.some((field) => manifest[field]?.[sibling.package] !== undefined);
+            if (!consumed)
+                return [sibling.package, null];
+            let hash = hashes.get(sibling);
+            if (!hash) {
+                hash = existsSync(sibling.dir)
+                    ? sourceHash(sibling.dir, [...sibling.sources])
+                    : ABSENT;
+                hashes.set(sibling, hash);
+            }
+            return [sibling.package, hash];
+        }));
+        const output = join(dir, ".turbo");
+        mkdirSync(output, { recursive: true });
+        writeFileSync(join(output, "siblings.json"), JSON.stringify(fingerprints) + "\n");
+    }
+}

package/dist/source-hash.d.ts

@@ -0,0 +1,2 @@
+/** SHA-256 over sorted Git-visible source paths and contents, excluding ignored files. */
+export declare function sourceHash(directory: string, sources: string[]): string;

package/dist/source-hash.js

@@ -0,0 +1,29 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** SHA-256 over sorted Git-visible source paths and contents, excluding ignored files. */
+export function sourceHash(directory, sources) {
+    const hash = createHash("sha256");
+    const listed = execFileSync("git", [
+        "-C",
+        directory,
+        "ls-files",
+        "-z",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "--",
+        ...sources,
+    ], { encoding: "utf8" });
+    const files = listed
+        .split("\0")
+        .filter((file) => file && existsSync(join(directory, file)))
+        .sort();
+    for (const file of files) {
+        hash.update(`${file}\0`);
+        hash.update(readFileSync(join(directory, file)));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}

package/dist/testkit/built-worker.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+/** The fields of a built `wrangler.json` deploys depend on. */
+export declare const BuiltWorkerConfig: z.ZodObject<{
+    hyperdrive: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        binding: z.ZodString;
+    }, z.core.$strip>>>;
+    secrets: z.ZodDefault<z.ZodObject<{
+        required: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    vars: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** A built worker's Hyperdrive bindings, required secrets and vars. */
+export type BuiltWorkerConfig = z.infer<typeof BuiltWorkerConfig>;
+/** `dir/wrangler.json` of a built worker (e.g. `dist/server`); absent
+ *  fields read empty. */
+export declare function readBuiltWorkerConfig(dir: string): Promise<BuiltWorkerConfig>;
+/** `dir`'s built worker's required secrets, valued from `environment`. */
+export declare function requiredSecrets(dir: string, environment: Readonly<Record<string, string | undefined>>): Promise<Record<string, string | undefined>>;
+/** `findInBundle` scope. */
+export interface FindInBundleOptions {
+    /** File extensions read, e.g. `[".js", ".css"]`. Default: scripts. */
+    extensions?: readonly string[];
+}
+/**
+ * `<file>: <needle>` for each of `needles` a file under `dir` contains,
+ * paths relative to `dir`: empty for a bundle free of them. Rejects when
+ * `dir` holds no file of `extensions`.
+ */
+export declare function findInBundle(dir: string, needles: string | readonly string[], { extensions }?: FindInBundleOptions): Promise<string[]>;

package/dist/testkit/built-worker.js

@@ -0,0 +1,48 @@
+/** Built-worker checks: the `wrangler.json` a Cloudflare Vite build writes,
+ *  and text a bundle's scripts carry. */
+import { readdir, readFile } from "node:fs/promises";
+import { extname, join, relative } from "node:path";
+import { z } from "zod";
+/** The fields of a built `wrangler.json` deploys depend on. */
+export const BuiltWorkerConfig = z.object({
+    hyperdrive: z.array(z.object({ binding: z.string() })).default([]),
+    secrets: z
+        .object({ required: z.array(z.string()).default([]) })
+        .default({ required: [] }),
+    vars: z.record(z.string(), z.unknown()).default({}),
+});
+/** `dir/wrangler.json` of a built worker (e.g. `dist/server`); absent
+ *  fields read empty. */
+export async function readBuiltWorkerConfig(dir) {
+    const text = await readFile(join(dir, "wrangler.json"), "utf8");
+    return BuiltWorkerConfig.parse(JSON.parse(text));
+}
+/** `dir`'s built worker's required secrets, valued from `environment`. */
+export async function requiredSecrets(dir, environment) {
+    const { required } = (await readBuiltWorkerConfig(dir)).secrets;
+    return Object.fromEntries(required.map((key) => [key, environment[key]]));
+}
+/** Script extensions `findInBundle` reads by default. */
+const SCRIPTS = [".js", ".mjs", ".cjs"];
+/**
+ * `<file>: <needle>` for each of `needles` a file under `dir` contains,
+ * paths relative to `dir`: empty for a bundle free of them. Rejects when
+ * `dir` holds no file of `extensions`.
+ */
+export async function findInBundle(dir, needles, { extensions = SCRIPTS } = {}) {
+    const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+    const files = entries
+        .filter((entry) => entry.isFile() && extensions.includes(extname(entry.name)))
+        .map((entry) => relative(dir, join(entry.parentPath, entry.name)))
+        .sort();
+    if (files.length === 0)
+        throw new Error(`no ${extensions.join(", ")} files under ${dir}`);
+    const found = [];
+    for (const file of files) {
+        const text = await readFile(join(dir, file), "utf8");
+        for (const needle of typeof needles === "string" ? [needles] : needles)
+            if (text.includes(needle))
+                found.push(`${file}: ${needle}`);
+    }
+    return found;
+}