@astralarium/repo-dev 0.0.0-stage → 0.1.0

package/dist/launcher/hosts.js

@@ -0,0 +1,152 @@
+/**
+ * Per-checkout hostnames, derived from where the checkout lives: browsers
+ * scope cookies by host, so checkouts on one machine keep separate
+ * sessions. Extra checkouts are git worktrees or temp-dir copies.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { networkInterfaces, tmpdir } from "node:os";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { output } from "../exec.js";
+import { runningSession } from "./servers.js";
+/** `live` session advertising the LAN hostname. */
+const MDNS_SESSION = "mdns";
+/** Longest DNS label. */
+const LABEL_LENGTH = 63;
+/** `name` as a DNS label: lowercase, runs outside `[a-z0-9-]` as `-`,
+ *  `-<suffix>` appended, at most 63 characters with `suffix` intact;
+ *  empty when nothing of `name` survives. */
+export function dnsLabel(name, suffix) {
+    const room = LABEL_LENGTH - (suffix === undefined ? 0 : suffix.length + 1);
+    const label = name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+/, "")
+        .slice(0, room)
+        .replace(/-+$/, "");
+    return label && suffix !== undefined ? `${label}-${suffix}` : label;
+}
+/** Temp directories, real paths: `os.tmpdir()`, macOS's per-user temp
+ *  directory (independent of `TMPDIR`), `/tmp`, `/var/tmp`. */
+export function tempRoots() {
+    const darwin = output("getconf", ["DARWIN_USER_TEMP_DIR"]);
+    const roots = [tmpdir(), ...(darwin ? [darwin] : []), "/tmp", "/var/tmp"];
+    return [
+        ...new Set(roots.flatMap((path) => {
+            try {
+                return [realpathSync(path)];
+            }
+            catch {
+                return [];
+            }
+        })),
+    ];
+}
+/** The checkout's hostname label; undefined for a main worktree. */
+function checkoutLabel(root, temps) {
+    for (const temp of temps) {
+        const inside = relative(temp, root);
+        const [first] = inside.split(sep);
+        if (!inside || first === ".." || isAbsolute(inside))
+            continue;
+        // Paths are unique: checkouts nested under one first directory differ in hash.
+        return inside === first
+            ? { name: first }
+            : {
+                name: first,
+                hash: createHash("sha256").update(inside).digest("hex").slice(0, 6),
+            };
+    }
+    if (output("git", ["--version"]) === null)
+        throw new ExpectedError(`git is unavailable; ${root} needs it to name its hostname`);
+    const lines = output("git", [
+        "-C",
+        root,
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-dir",
+        "--git-common-dir",
+    ])?.split("\n");
+    if (lines?.length !== 2)
+        throw new ExpectedError(`${root} is neither a git worktree nor under a temp directory; check out extra copies with git worktree add`);
+    const [gitDir, commonDir] = lines;
+    // A linked worktree's git dir, `.git/worktrees/<name>`, is unique per repository.
+    return gitDir === commonDir ? undefined : { name: basename(gitDir) };
+}
+/**
+ * The checkout's hostname stem: `<domain>` for a repository's main
+ * worktree, `<name>.<domain>` for a linked worktree (git's worktree name)
+ * or a checkout under a temp directory (its first directory below it,
+ * plus a hash of its path when deeper: `copy-1-ab12cd`). The temp-directory
+ * rule wins over git's worktree name.
+ */
+export function checkoutStem(app, temps = tempRoots()) {
+    const checkout = checkoutLabel(realpathSync(app.root), temps);
+    if (checkout === undefined)
+        return app.domain;
+    const label = dnsLabel(checkout.name, checkout.hash);
+    if (!label)
+        throw new ExpectedError(`checkout name ${checkout.name} yields no hostname label`);
+    return `${label}.${app.domain}`;
+}
+/** `DEV_LAN`: `1` serves the LAN as well, unset serves loopback only. */
+function lanEnabled(overrides) {
+    const value = overrides.DEV_LAN;
+    if (value !== undefined && value !== "1")
+        throw new ExpectedError("DEV_LAN must be 1 or unset");
+    return value === "1";
+}
+/** Hostnames and certificate paths of hostname stem `stem`. */
+export function localHosts(local, overrides, stem) {
+    const lan = lanEnabled(overrides);
+    const hostname = `${stem}.localhost`;
+    const lanHostname = `${stem}.local`;
+    const certDir = resolve(local, "certs");
+    return {
+        hostname,
+        lanHostname,
+        hostnames: lan ? [hostname, lanHostname] : [hostname],
+        lan,
+        sslKey: resolve(certDir, `${hostname}-key.pem`),
+        sslCert: resolve(certDir, `${hostname}.pem`),
+    };
+}
+/** IPv4 address `DEV_LAN` advertises: the default route interface's.
+ *  Throws `ExpectedError` without `dns-sd` or a default route. */
+export function lanAddress() {
+    if (output("which", ["dns-sd"]) === null)
+        throw new ExpectedError("DEV_LAN needs dns-sd (macOS Bonjour)");
+    const device = output("route", ["-n", "get", "default"])?.match(/interface: (\S+)/)?.[1];
+    const address = (device === undefined ? [] : networkInterfaces()[device])?.find(({ family, internal }) => family === "IPv4" && !internal)?.address;
+    if (address === undefined)
+        throw new ExpectedError("DEV_LAN needs a default route with an IPv4 address");
+    return address;
+}
+/** Stops the checkout's mDNS advertisement; a missing session is fine. */
+export function stopAdvertising(root) {
+    const session = runningSession(MDNS_SESSION, root);
+    if (session)
+        execFileSync("live", ["stop", session.id], { stdio: "inherit" });
+}
+/** Advertises `hosts.lanHostname` → `address` over mDNS (`dns-sd`)
+ *  under `live`, replacing a running advertisement. */
+export function advertiseHost(root, hosts, address, port) {
+    stopAdvertising(root);
+    execFileSync("live", [
+        "run",
+        "-dn",
+        MDNS_SESSION,
+        "-C",
+        root,
+        "dns-sd",
+        "-P",
+        hosts.lanHostname,
+        "_https._tcp",
+        "local",
+        String(port),
+        hosts.lanHostname,
+        address,
+    ], { stdio: "ignore" });
+}

package/dist/launcher/launcher.d.ts

@@ -0,0 +1,23 @@
+import { type Allocation } from "../allocation.ts";
+import { type DevConfig, type Overrides } from "../config.ts";
+/** `keys` from the shell over `envFile`; empty values count as unset. */
+export declare function readOverrides(envFile: string, keys: readonly string[], shell?: Record<string, string | undefined>): Overrides;
+/** Keys the launcher reads for `app`: its own plus `DEV_LAN`. */
+export declare function overrideKeys(app: DevConfig): string[];
+/** `<local>/auth-secret`, generated on first use. */
+export declare function authSecret(local: string): string;
+/**
+ * Keeps the saved allocation where it still holds: the database through
+ * its provider, server ports a running session of this checkout started
+ * on (per its state) or saved ports still free. Anything else moves to the
+ * next free port. The checkout root labels the database instance.
+ */
+export declare function allocate(app: Pick<DevConfig, "root" | "database" | "servers">, local: string, base: string): Promise<Allocation>;
+/**
+ * Dev server environments for one allocation on hostname stem `stem`
+ * (`checkoutStem`), keyed by server name: the app's `environment()` over
+ * each server's listener settings.
+ */
+export declare function devEnvironment(app: DevConfig, local: string, overrides: Overrides, allocation: Allocation, stem: string): Record<string, Record<string, string>>;
+/** See `usage`. */
+export declare function main(app: DevConfig, argv: string[]): Promise<void>;

package/dist/launcher/launcher.js

@@ -0,0 +1,452 @@
+/**
+ * Local dev launcher: generated state under `<root>/.local/`, the app's
+ * database, then its dev servers under `live` with the dev config as
+ * process env. Idempotent; `reset` is the only command that deletes data.
+ * Each checkout claims its own database instance and ports, so worktrees
+ * and other projects run side by side.
+ */
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs, parseEnv } from "node:util";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { z } from "zod";
+import { localDir, readAllocation } from "../allocation.js";
+import { ENV_KEY, envDbName, RESOURCE_NAME, } from "../config.js";
+import { listenerEnv } from "../environment.js";
+import { output } from "../exec.js";
+import { keepOrFindPort } from "../ports.js";
+import { setupResources } from "../resources.js";
+import { advertiseHost, checkoutStem, lanAddress, localHosts, stopAdvertising, } from "./hosts.js";
+import { httpReady, runningSession, sessionPorts, startDevServer, stopSession, } from "./servers.js";
+/** Commands `main` accepts for every app. */
+const COMMANDS = ["start", "stop", "certs"];
+/** Commands running a disposable database instance until it ends. */
+const DISPOSABLE_COMMANDS = ["temp-db", "upgrade-db", "run-snapshot"];
+/** Commands `main` accepts for an app with a database. */
+const DATABASE_COMMANDS = ["build", "reset", ...DISPOSABLE_COMMANDS];
+/** Commands taking `--db-name`. */
+const DB_NAME_COMMANDS = ["start", "stop", ...DATABASE_COMMANDS];
+/** Commands taking server arguments after `--`. */
+const SERVER_ARGS_COMMANDS = ["temp-db", "run-snapshot"];
+/** Usage for `app`: database commands and options only when it has one. */
+function usage(app) {
+    const database = app.database !== undefined;
+    return [
+        `Usage: ${app.program} [command]${database ? " [-y] [--db-name <name>]" : ""}`,
+        "",
+        `  start       ${database ? "database and " : ""}dev servers (default); makes missing certificates`,
+        `  stop        dev servers${database ? " and database" : ""}`,
+        ...(database
+            ? ["  build       refresh base images and rebuild database images"]
+            : []),
+        "  certs       install the local CA and regenerate HTTPS certificates",
+        ...(database
+            ? [
+                `  reset       stop, delete the local database (${app.data}), rebuild`,
+                "  temp-db [-- <server args>]",
+                "              disposable database on the current schema, until Ctrl-C",
+                "  upgrade-db [migrate.sql...]",
+                "              dump of the PG* database, migrated onto the current schema, to stdout",
+                "  run-snapshot [--no-scrub] <dump.sql> [-- <server args>]",
+                "              disposable database loaded from a dump, scrubbed unless --no-scrub",
+                "  -y, --yes   skip the reset confirmation",
+                `  --db-name   database image name and instance base (${DB_NAME_COMMANDS.join(", ")})`,
+            ]
+            : []),
+        "  -h, --help",
+    ].join("\n");
+}
+/** `keys` from the shell over `envFile`; empty values count as unset. */
+export function readOverrides(envFile, keys, shell = process.env) {
+    const file = existsSync(envFile)
+        ? parseEnv(readFileSync(envFile, "utf8"))
+        : {};
+    return Object.fromEntries(keys.flatMap((key) => {
+        const value = [shell[key], file[key]].find(Boolean);
+        return value ? [[key, value]] : [];
+    }));
+}
+/** Keys the launcher reads for `app`: its own plus `DEV_LAN`. */
+export function overrideKeys(app) {
+    return [...new Set([...app.overrideKeys, "DEV_LAN"])];
+}
+/** `<local>/auth-secret`, generated on first use. */
+export function authSecret(local) {
+    const path = resolve(local, "auth-secret");
+    if (!existsSync(path)) {
+        mkdirSync(local, { recursive: true });
+        writeFileSync(path, randomBytes(32).toString("hex"), { mode: 0o600 });
+    }
+    return readFileSync(path, "utf8").trim();
+}
+/** Live session state of the launched servers: `<local>/servers/`. */
+function serverStateDir(local) {
+    return resolve(local, "servers");
+}
+/**
+ * Keeps the saved allocation where it still holds: the database through
+ * its provider, server ports a running session of this checkout started
+ * on (per its state) or saved ports still free. Anything else moves to the
+ * next free port. The checkout root labels the database instance.
+ */
+export async function allocate(app, local, base) {
+    const saved = readAllocation(local);
+    const database = app.database
+        ? await app.database.allocate({
+            base,
+            owner: app.root,
+            saved: saved.database ?? {},
+        })
+        : undefined;
+    const ports = {};
+    const inspectorPorts = {};
+    // Ports this allocation already holds: a free-port search skips them.
+    const taken = new Set(database ? [database.port] : []);
+    const keep = async (started, kept, preferred) => {
+        const port = started ?? (await keepOrFindPort(kept, preferred, taken));
+        taken.add(port);
+        return port;
+    };
+    for (const server of app.servers) {
+        const session = runningSession(server.name, resolve(app.root, server.dir));
+        const started = session && sessionPorts(serverStateDir(local), server.name, session.id);
+        ports[server.name] = await keep(started?.port, saved.ports?.[server.name], server.port);
+        if (server.inspectorPort !== undefined)
+            inspectorPorts[server.name] = await keep(started?.inspectorPort, saved.inspectorPorts?.[server.name], server.inspectorPort);
+    }
+    const allocation = { ports, inspectorPorts };
+    if (database)
+        allocation.database = database;
+    mkdirSync(local, { recursive: true });
+    writeFileSync(resolve(local, "dev.json"), JSON.stringify(allocation));
+    return allocation;
+}
+/** Origin of `server` on `port` at `hostname`. */
+function serverOrigin(server, port, hostname = "localhost") {
+    return `${server.https ? "https" : "http"}://${hostname}:${port}`;
+}
+/** Allocated servers by name; `host` servers on the checkout
+ *  hostnames. */
+function serverAllocations(app, allocation, hosts) {
+    return Object.fromEntries(app.servers.map((server) => {
+        const port = allocation.ports[server.name];
+        const inspectorPort = allocation.inspectorPorts[server.name];
+        const origins = server.host
+            ? hosts.hostnames.map((host) => serverOrigin(server, port, host))
+            : [serverOrigin(server, port)];
+        return [
+            server.name,
+            {
+                port,
+                origin: serverOrigin(server, port, server.host ? hosts.hostname : undefined),
+                origins,
+                ...(inspectorPort !== undefined && { inspectorPort }),
+            },
+        ];
+    }));
+}
+/** What `environment()` returns: string values under environment names. */
+const serverEnvironments = z.record(z.string(), z.record(z.string().regex(ENV_KEY), z.string()));
+/**
+ * Dev server environments for one allocation on hostname stem `stem`
+ * (`checkoutStem`), keyed by server name: the app's `environment()` over
+ * each server's listener settings.
+ */
+export function devEnvironment(app, local, overrides, allocation, stem) {
+    const hosts = localHosts(local, overrides, stem);
+    const result = serverEnvironments.safeParse(app.environment({
+        localDir: local,
+        overrides,
+        hosts,
+        authSecret: authSecret(local),
+        database: app.database && allocation.database
+            ? {
+                ...allocation.database,
+                connectionString: app.database.connectionString(allocation.database),
+            }
+            : undefined,
+        servers: serverAllocations(app, allocation, hosts),
+    }));
+    if (!result.success)
+        throw new ExpectedError(`environment() must return string values under environment names per server:\n${z.prettifyError(result.error)}`);
+    const env = result.data;
+    return Object.fromEntries(app.servers.map((server) => {
+        const own = env[server.name];
+        if (!own)
+            throw new ExpectedError(`environment() returned no env for ${server.name}`);
+        return [
+            server.name,
+            {
+                ...listenerEnv(hosts, server, allocation.inspectorPorts[server.name]),
+                ...own,
+            },
+        ];
+    }));
+}
+/** Installs the mkcert CA and generates the checkout's certificate
+ *  (`localhost` and both checkout hostnames); an existing one stays
+ *  unless `force`. */
+function installCertificates({ hostname, lanHostname, sslKey, sslCert }, force = false) {
+    execFileSync("mkcert", ["-install"], { stdio: "inherit" });
+    if (!force && existsSync(sslKey) && existsSync(sslCert))
+        return;
+    mkdirSync(resolve(sslKey, ".."), { recursive: true });
+    execFileSync("mkcert", [
+        "-key-file",
+        sslKey,
+        "-cert-file",
+        sslCert,
+        "localhost",
+        hostname,
+        lanHostname,
+    ], { stdio: "inherit" });
+}
+/** Starts every dev server concurrently and waits for HTTP readiness. */
+async function startServers(app, resources, local, env, allocation) {
+    const stateDir = serverStateDir(local);
+    const lockfile = resolve(app.root, "pnpm-lock.yaml");
+    const ca = app.servers.some((server) => server.https)
+        ? readFileSync(resolve(execFileSync("mkcert", ["-CAROOT"], { encoding: "utf8" }).trim(), "rootCA.pem"))
+        : undefined;
+    await Promise.all(app.servers.map((server) => {
+        const port = allocation.ports[server.name];
+        const inspectorPort = allocation.inspectorPorts[server.name];
+        const origin = serverOrigin(server, port);
+        const own = env[server.name];
+        return startDevServer(resources, {
+            name: server.name,
+            appDir: resolve(app.root, server.dir),
+            stateDir,
+            port,
+            ...(inspectorPort !== undefined && { inspectorPort }),
+            env: own,
+            inputs: [lockfile, own.SSL_KEY, own.SSL_CERT].filter((file) => file !== undefined && file !== ""),
+            ca: server.https ? ca : undefined,
+            probe: async (agent) => (await Promise.all(server.ready.map(({ path, status, body }) => httpReady(`${origin}${path}`, agent, {
+                status,
+                body,
+                signal: resources.signal,
+            })))).every(Boolean),
+        });
+    }));
+}
+/** Stops every `live` session, the mDNS advertisement included, and waits
+ *  for its ports to close: those its state records, else the saved
+ *  allocation's; missing sessions are fine. */
+async function stopServers(app, local) {
+    const saved = readAllocation(local);
+    await Promise.all([
+        Promise.resolve().then(() => {
+            stopAdvertising(app.root);
+        }),
+        ...app.servers.map(async ({ name, dir }) => {
+            const session = runningSession(name, resolve(app.root, dir));
+            if (session)
+                await stopSession(name, session.id, sessionPorts(serverStateDir(local), name, session.id) ?? {
+                    port: saved.ports?.[name],
+                    inspectorPort: saved.inspectorPorts?.[name],
+                });
+        }),
+    ]);
+}
+/** Interactive `[y/N]`; a non-interactive session must pass `--yes`. */
+async function confirmReset(data) {
+    if (!process.stdin.isTTY) {
+        throw new ExpectedError(`reset deletes the local database (${data}); pass --yes to confirm non-interactively`);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`Delete the local database (${data})? [y/N] `);
+        if (!/^y(es)?$/i.test(answer.trim()))
+            throw new ExpectedError("reset aborted");
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Throws an install hint unless `name args` exits 0. */
+function requireTool(name, args) {
+    if (output(name, args) === null)
+        throw new ExpectedError(`${name} is unavailable; install it (see @astralarium/repo-dev README)`);
+}
+/** The launcher's command line; throws on an unknown option. Positionals
+ *  after `--` are server arguments. */
+function parseLauncherArgs(argv) {
+    const { values, tokens } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        tokens: true,
+        options: {
+            yes: { type: "boolean", short: "y", default: false },
+            help: { type: "boolean", short: "h", default: false },
+            "db-name": { type: "string" },
+            "no-scrub": { type: "boolean" },
+        },
+    });
+    const terminator = tokens.find((token) => token.kind === "option-terminator");
+    return {
+        values,
+        positionals: tokens.flatMap((token) => token.kind === "positional" &&
+            (terminator === undefined || token.index < terminator.index)
+            ? [token.value]
+            : []),
+        serverArgs: terminator ? argv.slice(terminator.index + 1) : [],
+    };
+}
+/** `operands` and `serverArgs` fit `mode`: a dump for `run-snapshot`, migrate
+ *  files for `upgrade-db`, none otherwise. */
+function argumentsFit(mode, operands, serverArgs) {
+    return ((mode === "upgrade-db" ||
+        operands.length === (mode === "run-snapshot" ? 1 : 0)) &&
+        (serverArgs.length === 0 || SERVER_ARGS_COMMANDS.includes(mode)));
+}
+/** Runs `command` until it settles; SIGINT and SIGTERM abort its signal. */
+async function untilInterrupted(command) {
+    const controller = new AbortController();
+    const stop = () => {
+        controller.abort();
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    try {
+        await command(controller.signal);
+    }
+    finally {
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+    }
+}
+/** See `usage`. */
+export async function main(app, argv) {
+    let parsed;
+    try {
+        parsed = parseLauncherArgs(argv);
+    }
+    catch (cause) {
+        throw new ExpectedError(usage(app), { cause });
+    }
+    const { values, positionals, serverArgs } = parsed;
+    if (values.help) {
+        console.log(usage(app));
+        return;
+    }
+    const [mode = "start", ...operands] = positionals;
+    const commands = app.database
+        ? [...COMMANDS, ...DATABASE_COMMANDS]
+        : COMMANDS;
+    const databaseName = values["db-name"] ?? (app.database ? envDbName(app.database) : "");
+    if (!commands.includes(mode) ||
+        !argumentsFit(mode, operands, serverArgs) ||
+        (app.database === undefined &&
+            (values.yes || values["db-name"] !== undefined)) ||
+        (app.database !== undefined && !RESOURCE_NAME.test(databaseName)))
+        throw new ExpectedError(usage(app));
+    if (values["db-name"] !== undefined && !DB_NAME_COMMANDS.includes(mode))
+        throw new ExpectedError(`--db-name applies to ${DB_NAME_COMMANDS.join(", ")}`);
+    if (values["no-scrub"] !== undefined && mode !== "run-snapshot")
+        throw new ExpectedError("--no-scrub applies to run-snapshot");
+    const serves = mode === "start" || mode === "reset";
+    if (serves)
+        requireTool("live", ["--version"]);
+    if (mode === "certs" ||
+        (serves && app.servers.some((server) => server.https)))
+        requireTool("mkcert", ["-version"]);
+    const local = localDir(app.root);
+    if (mode === "reset" && !values.yes)
+        await confirmReset(app.data);
+    if (mode === "stop") {
+        try {
+            requireTool("live", ["--version"]);
+            await stopServers(app, local);
+        }
+        finally {
+            app.database?.stop(values["db-name"] ??
+                readAllocation(local).database?.name ??
+                databaseName, app.root);
+        }
+        return;
+    }
+    if (mode === "build") {
+        app.database?.build(databaseName);
+        return;
+    }
+    const database = app.database;
+    if (database && DISPOSABLE_COMMANDS.includes(mode)) {
+        // pnpm runs scripts and bins in the package directory; INIT_CWD holds
+        // the developer's.
+        // eslint-disable-next-line turbo/no-undeclared-env-vars -- no turbo task runs this CLI
+        const cwd = process.env.INIT_CWD ?? process.cwd();
+        const files = operands.map((file) => resolve(cwd, file));
+        const allocation = await database.allocate({
+            base: databaseName,
+            owner: app.root,
+            saved: readAllocation(local).database ?? {},
+        });
+        await untilInterrupted((signal) => mode === "upgrade-db"
+            ? database.upgradeDump({
+                allocation,
+                image: databaseName,
+                migrations: files,
+                signal,
+            })
+            : database.runDisposable({
+                allocation,
+                image: databaseName,
+                serverArgs,
+                ...(mode === "run-snapshot" && {
+                    snapshot: { dump: files[0], scrub: !values["no-scrub"] },
+                }),
+                signal,
+            }));
+        return;
+    }
+    const overrides = readOverrides(resolve(app.root, ".env"), overrideKeys(app));
+    const stem = checkoutStem(app);
+    const hosts = localHosts(local, overrides, stem);
+    if (mode === "certs") {
+        installCertificates(hosts, true);
+        return;
+    }
+    if (app.servers.some((server) => server.https) &&
+        !(existsSync(hosts.sslKey) && existsSync(hosts.sslCert)))
+        installCertificates(hosts);
+    const address = hosts.lan ? lanAddress() : undefined;
+    if (mode === "reset")
+        await stopServers(app, local);
+    const allocation = await allocate(app, local, databaseName);
+    const env = devEnvironment(app, local, overrides, allocation, stem);
+    const servers = serverAllocations(app, allocation, hosts);
+    await setupResources(async (resources) => {
+        if (app.database && allocation.database) {
+            if (mode === "reset")
+                app.database.reset(allocation.database.name, databaseName);
+            await app.database.ensure(resources, {
+                allocation: allocation.database,
+                image: databaseName,
+                owner: app.root,
+                program: app.program,
+            });
+        }
+        await startServers(app, resources, local, env, allocation);
+        const lanServer = app.servers.find((server) => server.host);
+        if (address !== undefined && lanServer)
+            advertiseHost(app.root, hosts, address, allocation.ports[lanServer.name]);
+        else
+            stopAdvertising(app.root);
+        resources.release();
+    });
+    log.info("dev.ready", "{servers}{hasDatabase, select, true {  database: {name} on 127.0.0.1:{port}} other {}}", {
+        servers: app.servers
+            .map(({ name }) => `${name}: ${servers[name].origins.join(",")}`)
+            .concat(address === undefined
+            ? []
+            : [`mdns: ${hosts.lanHostname} → ${address}`])
+            .join("  "),
+        hasDatabase: allocation.database !== undefined,
+        name: allocation.database?.name,
+        port: allocation.database?.port,
+    });
+}

package/dist/launcher/servers.d.ts

@@ -0,0 +1,39 @@
+import { Agent } from "undici";
+import type { ResourceScope } from "../resources.ts";
+/** Ports a dev server listens on. */
+export interface ServerPorts {
+    /** HTTP listener. */
+    port: number;
+    /** Debugger; present when the server declares one. */
+    inspectorPort?: number;
+}
+/** Hashes the effective app config and the contents of `files`; stores no
+ *  credential values. */
+export declare function configFingerprint(env: Record<string, string>, files?: readonly string[]): string;
+/** Running session `name`, scoped to `appDir`, where `live run -C` put it. */
+export declare function runningSession(name: string, appDir: string): {
+    id: string;
+} | undefined;
+/** Ports session `id` of `name` started on, per its state in `stateDir`;
+ *  undefined when the state records another session. */
+export declare function sessionPorts(stateDir: string, name: string, id: string): ServerPorts | undefined;
+/** Stops session `id` of `name`, then waits for each of its ports to close. */
+export declare function stopSession(name: string, id: string, { port, inspectorPort }: Partial<ServerPorts>, signal?: AbortSignal): Promise<void>;
+/** HTTP readiness through the actual listener, including TLS and optional body checks. */
+export declare function httpReady(url: string, agent: Agent, options?: {
+    status?: number;
+    body?: string;
+    signal?: AbortSignal;
+}): Promise<boolean>;
+/** Starts or reconciles one dev service; rollback owns only the new session. */
+export declare function startDevServer(resources: ResourceScope, options: ServerPorts & {
+    name: string;
+    appDir: string;
+    stateDir: string;
+    env: Record<string, string>;
+    /** Files whose contents restart the session on change: the dependency
+     *  lockfile (stale prebundled deps), TLS certificates. */
+    inputs?: readonly string[];
+    ca?: Buffer;
+    probe: (agent: Agent) => Promise<boolean>;
+}): Promise<void>;