@axis-network/butter-col 0.0.0-stage → 0.1.0

package/dist/types/formatter/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * butter-col formatter: everything that turns a target site's content into
+ * content that keeps working when served from the proxy origin.
+ *
+ * It is shared by the service worker (src/sw) and the in-page runtime
+ * (src/client) and has no dependencies on either environment beyond the
+ * standard URL / TextEncoder APIs.
+ */
+import { MODULE_WORKER_MARK } from "./url.js";
+import { rewriteCss } from "./css.js";
+import { rewriteJs, LOCATION, EVAL_WRAP, UNREWRITE } from "./js.js";
+import { rewriteHtml, URL_ATTRS, decodeEntities, escapeAttribute } from "./html.js";
+import { codecs, getCodec } from "./codecs.js";
+export type FormatterConfig = {
+    /**
+     * Proxy origin
+     */
+    origin: string;
+    /**
+     * Prefix for proxied URLs, e.g. "/butter/go/"
+     */
+    prefix: string;
+    /**
+     * Codec name
+     */
+    codec: string;
+};
+/**
+ * @typedef {object} FormatterConfig
+ * @property {string} origin  Proxy origin
+ * @property {string} prefix  Prefix for proxied URLs, e.g. "/butter/go/"
+ * @property {string} codec   Codec name
+ */
+/**
+ * @param {FormatterConfig} config
+ */
+export declare function createFormatter(config: FormatterConfig): {
+    config: FormatterConfig;
+    url: {
+        origin: string;
+        prefix: string;
+        codec: import("./codecs.js").Codec;
+        decodeTail: (tail: string) => string | null;
+        isProxied: (url: string) => boolean;
+        rewrite: (raw: string, base: string | URL, opts?: {
+            moduleWorker?: boolean;
+        }) => string;
+        unrewrite: (url: string) => string;
+        rewriteSrcset: (value: string, base: string | URL, map?: (url: string, base: string | URL) => string) => string;
+        unrewriteSrcset: (value: any) => string;
+    };
+    /** @param {string} raw @param {string | URL} base @param {{ moduleWorker?: boolean }} [opts] */
+    rewriteUrl: (raw: string, base: string | URL, opts?: {
+        moduleWorker?: boolean;
+    }) => string;
+    /** @param {string} proxied */
+    unrewriteUrl: (proxied: string) => string;
+    /** @param {string} src @param {string | URL} base */
+    css: (src: string, base: string | URL) => string;
+    /** @param {string} src */
+    js: (src: string) => string;
+    /** @param {string} src @param {{ base: string, inject?: string }} options */
+    html: (src: string, options: {
+        base: string;
+        inject?: string;
+    }) => string;
+    /** @param {string} tag @param {string} name @param {string} value @param {{ base: string, inject?: string }} ctx */
+    attr: (tag: string, name: string, value: string, ctx: {
+        base: string;
+        inject?: string;
+    }) => string;
+    /** @param {string} value @param {string} base */
+    refresh: (value: string, base: string) => string;
+};
+export type Formatter = ReturnType<typeof createFormatter>;
+/** @typedef {ReturnType<typeof createFormatter>} Formatter */
+export { codecs, getCodec, rewriteCss, rewriteJs, rewriteHtml, decodeEntities, escapeAttribute, URL_ATTRS, MODULE_WORKER_MARK, LOCATION, EVAL_WRAP, UNREWRITE, };

package/dist/types/formatter/js.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JavaScript rewriting.
+ *
+ * butter-col does not parse JavaScript into an AST. Instead a small,
+ * error-tolerant tokenizer walks the source and applies a handful of targeted
+ * edits. Everything else (fetches, imports, workers, ...) is handled at
+ * runtime by the service worker and the client hooks, so the rewriter only
+ * has to deal with what cannot be hooked:
+ *
+ *   location / x.location / x?.location / x["location"]
+ *       -> __butter$location   (resolved by an accessor on Object.prototype)
+ *   eval(code)
+ *       -> eval(__butter$js(code))   (stays a *direct* eval)
+ *   import.meta.url
+ *       -> __butter$unrewrite(import.meta.url)
+ *
+ * The tokenizer never edits inside strings, template text, comments or regex
+ * literals, and every edit is local, so a mis-scan can at worst miss an edit.
+ */
+export declare const LOCATION = "__butter$location";
+export declare const EVAL_WRAP = "__butter$js";
+export declare const UNREWRITE = "__butter$unrewrite";
+/**
+ * @param {string} src
+ * @returns {string}
+ */
+export declare function rewriteJs(src: string): string;

package/dist/types/formatter/url.d.ts

@@ -0,0 +1,40 @@
+/** Marker placed after the prefix for module workers: /butter/go/~m/<encoded> */
+export declare const MODULE_WORKER_MARK = "~m/";
+export type UrlRewriterOptions = {
+    /**
+     * Proxy origin, e.g. "https://proxy.example"
+     */
+    origin: string;
+    /**
+     * Path prefix for proxied URLs, e.g. "/butter/go/"
+     */
+    prefix: string;
+    /**
+     * Codec name, see codecs.js
+     */
+    codec: string;
+};
+/**
+ * @typedef {object} UrlRewriterOptions
+ * @property {string} origin  Proxy origin, e.g. "https://proxy.example"
+ * @property {string} prefix  Path prefix for proxied URLs, e.g. "/butter/go/"
+ * @property {string} codec   Codec name, see codecs.js
+ */
+/**
+ * @param {UrlRewriterOptions} options
+ */
+export declare function createUrlRewriter({ origin, prefix, codec: codecName }: UrlRewriterOptions): {
+    origin: string;
+    prefix: string;
+    codec: import("./codecs.js").Codec;
+    decodeTail: (tail: string) => string | null;
+    isProxied: (url: string) => boolean;
+    rewrite: (raw: string, base: string | URL, opts?: {
+        moduleWorker?: boolean;
+    }) => string;
+    unrewrite: (url: string) => string;
+    rewriteSrcset: (value: string, base: string | URL, map?: (url: string, base: string | URL) => string) => string;
+    unrewriteSrcset: (value: any) => string;
+};
+export type UrlRewriter = ReturnType<typeof createUrlRewriter>;
+/** @typedef {ReturnType<typeof createUrlRewriter>} UrlRewriter */

package/lib/cli.js

@@ -0,0 +1,257 @@
+/**
+ * The `butter-col` command line.
+ *
+ *   butter-col server start [options]     run OpenResty (foreground)
+ *   butter-col server stop|reload|test    control a running server
+ *   butter-col fetch-ca                   download Mozilla's CA bundle
+ *   butter-col transport add <pkg|file>   make a transport servable
+ *   butter-col transport list
+ *   butter-col static <outdir> [options]  build a serverless deployment
+ *   butter-col paths                      print package paths as JSON
+ */
+import { spawn } from "node:child_process";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import {
+  createConfigScript,
+  createPublicConfig,
+  defaultConfigPath,
+  distPath,
+  findOpenResty,
+  luaPath,
+  packageRoot,
+  renderServerConfig,
+  resolveTransport,
+  serverPath,
+  sitePath,
+  transportsPath,
+  version,
+} from "./index.js";
+
+const HELP = `butter-col ${version}
+
+Usage:
+  butter-col server start   [--port 8080] [--site <dir>] [--config <file>] [--runtime .butter]
+                            [--transports butter-transports] [--cacert <file>] [--openresty <bin>]
+  butter-col server stop|reload|test   (same options)
+  butter-col fetch-ca       [--runtime .butter]
+  butter-col transport add  <package-or-file> [--name <name>] [--transports butter-transports]
+  butter-col transport list [--transports butter-transports]
+  butter-col static <outdir> [--config butter.static.json] [--site <dir>] [--transports butter-transports]
+  butter-col paths
+
+Defaults:
+  --config     ./butter.config.lua if it exists, else the package default
+  --site       the package's minimal launcher
+  --runtime    ./.butter   (rendered nginx config, logs, cacert.pem, served transports)
+  --transports ./butter-transports   (scripts added with "transport add")
+`;
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const [key, inline] = arg.slice(2).split("=", 2);
+      if (inline !== undefined) flags[key] = inline;
+      else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) flags[key] = argv[++i];
+      else flags[key] = true;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
+}
+
+const log = (...args) => console.log("[butter-col]", ...args);
+
+function fail(message) {
+  console.error(`butter-col: ${message}`);
+  process.exit(1);
+}
+
+function options(flags) {
+  const cwd = process.cwd();
+  const runtimeDir = path.resolve(cwd, flags.runtime ?? ".butter");
+  const localConfig = path.resolve(cwd, "butter.config.lua");
+  return {
+    cwd,
+    runtimeDir,
+    listen: flags.port ?? flags.listen ?? 8080,
+    siteRoot: flags.site ? path.resolve(cwd, flags.site) : sitePath,
+    configFile: flags.config ? path.resolve(cwd, flags.config) : existsSync(localConfig) ? localConfig : defaultConfigPath,
+    transportsDir: path.resolve(cwd, flags.transports ?? "butter-transports"),
+    cacert: flags.cacert ? path.resolve(cwd, flags.cacert) : path.join(runtimeDir, "cacert.pem"),
+    openresty: flags.openresty ?? findOpenResty(cwd),
+  };
+}
+
+async function fetchCa(target) {
+  const source = "https://curl.se/ca/cacert.pem";
+  const res = await fetch(source);
+  if (!res.ok) throw new Error(`GET ${source} failed: HTTP ${res.status}`);
+  const pem = await res.text();
+  const count = (pem.match(/-----BEGIN CERTIFICATE-----/g) || []).length;
+  if (count < 50) throw new Error(`unexpected CA bundle contents (${count} certificates)`);
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, pem);
+  log(`wrote ${count} certificates to ${path.relative(process.cwd(), target) || target}`);
+}
+
+/** Copy built-in and added transports to where nginx serves /butter/transports/. */
+function stageTransports(opts) {
+  const served = path.join(opts.runtimeDir, "www", "butter", "transports");
+  mkdirSync(served, { recursive: true });
+  const copied = [];
+  for (const dir of [transportsPath, opts.transportsDir]) {
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (!/\.js(\.map)?$/.test(file)) continue;
+      copyFileSync(path.join(dir, file), path.join(served, file));
+      if (file.endsWith(".js")) copied.push(file.replace(/\.js$/, ""));
+    }
+  }
+  return copied;
+}
+
+function prepareRuntime(opts) {
+  if (!existsSync(path.join(distPath, "sw.js"))) fail(`${distPath} is missing; build the package first (npm run build)`);
+  const confDir = path.join(opts.runtimeDir, "conf");
+  mkdirSync(confDir, { recursive: true });
+  mkdirSync(path.join(opts.runtimeDir, "logs"), { recursive: true });
+  const files = renderServerConfig(opts);
+  for (const [name, contents] of Object.entries(files)) writeFileSync(path.join(confDir, name), contents);
+  return stageTransports(opts);
+}
+
+function runOpenResty(opts, extra) {
+  const binary = opts.openresty;
+  // Windows builds resolve their bundled lualib/ relative to the working directory.
+  const cwd = path.isAbsolute(binary) ? path.dirname(binary) : opts.cwd;
+  const args = ["-p", opts.runtimeDir + path.sep, "-c", "conf/nginx.conf", ...extra];
+  const child = spawn(binary, args, { cwd, stdio: "inherit" });
+  child.on("error", (err) => fail(`could not run ${binary}: ${err.message}. Install OpenResty or pass --openresty <path>.`));
+  return child;
+}
+
+async function server(command, flags) {
+  const opts = options(flags);
+  if (command === "stop") {
+    runOpenResty(opts, ["-s", "stop"]).on("exit", (code) => process.exit(code ?? 0));
+    return;
+  }
+  if (!["start", "reload", "test"].includes(command)) fail(`unknown server command "${command}"`);
+  if (!existsSync(opts.cacert)) {
+    log("no CA bundle yet; downloading one");
+    await fetchCa(opts.cacert);
+  }
+  const transports = prepareRuntime(opts);
+  if (command === "test") {
+    runOpenResty(opts, ["-t"]).on("exit", (code) => process.exit(code ?? 0));
+    return;
+  }
+  if (command === "reload") {
+    runOpenResty(opts, ["-s", "reload"]).on("exit", (code) => process.exit(code ?? 0));
+    return;
+  }
+
+  log(`config     ${opts.configFile}`);
+  log(`site       ${opts.siteRoot}`);
+  log(`transports ${transports.join(", ")}`);
+  log(`listening  http://localhost:${opts.listen}/`);
+  const extra = process.platform === "win32" ? [] : ["-g", "daemon off;"];
+  const child = runOpenResty(opts, extra);
+  const stop = () => runOpenResty(opts, ["-s", "stop"]);
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+function transportAdd(specifier, flags) {
+  if (!specifier) fail("usage: butter-col transport add <package-or-file>");
+  const info = resolveTransport(specifier);
+  const name = flags.name ?? info.name;
+  const dir = path.resolve(flags.transports ?? "butter-transports");
+  mkdirSync(dir, { recursive: true });
+  copyFileSync(info.file, path.join(dir, `${name}.js`));
+  if (existsSync(info.file + ".map")) copyFileSync(info.file + ".map", path.join(dir, `${name}.js.map`));
+  log(`added transport "${name}"${info.packageName ? ` from ${info.packageName}@${info.version}` : ""} → ${path.relative(process.cwd(), dir)}/${name}.js`);
+  console.log(`
+Offer it in butter.config.lua:
+
+  transports = {
+    { name = "butter" },
+    { name = "${name}", options = { --[[ see the transport's README ]] } },
+  },
+`);
+}
+
+function transportList(flags) {
+  const dir = path.resolve(flags.transports ?? "butter-transports");
+  const list = (d) => (existsSync(d) ? readdirSync(d).filter((f) => f.endsWith(".js")).map((f) => f.slice(0, -3)) : []);
+  console.log(`built in: ${list(transportsPath).join(", ") || "(none)"}`);
+  console.log(`added (${path.relative(process.cwd(), dir) || dir}): ${list(dir).join(", ") || "(none)"}`);
+}
+
+function buildStatic(outdir, flags) {
+  if (!outdir) fail("usage: butter-col static <outdir> [--config butter.static.json]");
+  const out = path.resolve(outdir);
+  const configPath = path.resolve(flags.config ?? "butter.static.json");
+  if (!existsSync(configPath)) fail(`${configPath} not found (see the docs: "Serverless deployments")`);
+  const publicConfig = createPublicConfig(JSON.parse(readFileSync(configPath, "utf8")));
+  if (publicConfig.transports.some((t) => t.name === "butter")) {
+    log('warning: the "butter" transport needs the OpenResty server and will not work in a static deployment');
+  }
+
+  const butterDir = path.join(out, "butter");
+  mkdirSync(butterDir, { recursive: true });
+  cpSync(distPath, butterDir, { recursive: true, filter: (src) => !src.includes(`${path.sep}types`) });
+  const transportsDir = path.join(butterDir, "transports");
+  const extra = path.resolve(flags.transports ?? "butter-transports");
+  if (existsSync(extra)) cpSync(extra, transportsDir, { recursive: true });
+  writeFileSync(path.join(butterDir, "config.js"), createConfigScript(publicConfig));
+
+  const site = flags.site ? path.resolve(flags.site) : sitePath;
+  cpSync(site, out, { recursive: true, force: false, errorOnExist: false });
+  // Static hosts serve 404.html for unknown paths: let it bootstrap /butter/go/ URLs.
+  if (!existsSync(path.join(out, "404.html"))) copyFileSync(path.join(distPath, "bootstrap.html"), path.join(out, "404.html"));
+
+  for (const t of publicConfig.transports) {
+    const local = t.url.startsWith(publicConfig.base) ? path.join(out, t.url) : null;
+    if (local && !existsSync(local)) log(`warning: transport "${t.name}" points at ${t.url}, which is not in the output`);
+  }
+  log(`static deployment written to ${out}`);
+  log("serve it over HTTPS, with Service-Worker-Allowed: / on /butter/sw.js (or register with scope /butter/)");
+}
+
+export async function main(argv) {
+  const { positional, flags } = parseArgs(argv);
+  const [command, sub, arg] = positional;
+  try {
+    switch (command) {
+      case "server":
+        return await server(sub ?? "start", flags);
+      case "fetch-ca":
+        return await fetchCa(options(flags).cacert);
+      case "transport":
+        if (sub === "add") return transportAdd(arg, flags);
+        if (sub === "list") return transportList(flags);
+        return fail('usage: butter-col transport add|list');
+      case "static":
+        return buildStatic(sub, flags);
+      case "paths":
+        return console.log(JSON.stringify({ packageRoot, distPath, transportsPath, serverPath, luaPath, sitePath, defaultConfigPath }, null, 2));
+      case undefined:
+      case "help":
+      case "--help":
+        return console.log(HELP);
+      default:
+        if (flags.help || flags.h) return console.log(HELP);
+        if (flags.version || flags.v) return console.log(version);
+        return fail(`unknown command "${command}"\n\n${HELP}`);
+    }
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+}

package/lib/index.d.ts

@@ -0,0 +1,68 @@
+import type { ButterPublicConfig } from "@axis-network/butter-transport";
+
+/** Root of the installed package. */
+export declare const packageRoot: string;
+/** Built browser files: sw.js, client.js, controller.mjs, formatter.mjs, bootstrap.html, transports/. */
+export declare const distPath: string;
+/** Built-in transport scripts (dist/transports). */
+export declare const transportsPath: string;
+/** OpenResty files: conf templates, lua/, default config.lua. */
+export declare const serverPath: string;
+/** Lua modules (server/lua). */
+export declare const luaPath: string;
+/** Minimal launcher site, used when no --site is given. */
+export declare const sitePath: string;
+/** Default server configuration (server/config.lua). */
+export declare const defaultConfigPath: string;
+export declare const version: string;
+
+export interface StaticTransportEntry {
+  name: string;
+  /** Defaults to /butter/transports/<name>.js */
+  url?: string;
+  options?: unknown;
+}
+
+export interface StaticConfig {
+  /** Default "/butter/go/". */
+  prefix?: string;
+  /** "none" | "plain" | "xor" | "base64" (default "plain"). */
+  codec?: string;
+  transports: StaticTransportEntry[];
+  /** Default: the first transport. */
+  defaultTransport?: string;
+}
+
+/** Build the public configuration (/butter/config.js contents) without the Lua server. */
+export declare function createPublicConfig(input: StaticConfig): ButterPublicConfig;
+
+/** The JavaScript for /butter/config.js. */
+export declare function createConfigScript(publicConfig: ButterPublicConfig): string;
+
+export interface RenderOptions {
+  listen?: string | number;
+  siteRoot?: string;
+  configFile?: string;
+  runtimeDir: string;
+  cacert: string;
+}
+
+/** Render the OpenResty configuration files for a runtime directory. */
+export declare function renderServerConfig(options: RenderOptions): {
+  "nginx.conf": string;
+  "butter-proxy.conf": string;
+  "mime.types": string;
+};
+
+export interface ResolvedTransport {
+  name: string;
+  file: string;
+  packageName?: string;
+  version?: string;
+}
+
+/** Locate a transport package's browser script (package.json "butter.transport"). */
+export declare function resolveTransport(specifier: string, from?: string): ResolvedTransport;
+
+/** Find an OpenResty binary ($OPENRESTY, .tools/openresty-*, or "openresty"). */
+export declare function findOpenResty(cwd?: string): string;

package/lib/index.js

@@ -0,0 +1,166 @@
+/**
+ * @axis-network/butter-col: Node API.
+ *
+ *   import { distPath } from "@axis-network/butter-col";
+ *   app.use("/butter/", express.static(distPath));
+ *
+ * Paths to the built files, helpers to produce /butter/config.js for static
+ * deployments, nginx config rendering for the OpenResty server, and transport
+ * package resolution. The `butter-col` CLI is built on these.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Root of the installed package. */
+export const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+/** Built browser files: sw.js, client.js, controller.mjs, formatter.mjs, bootstrap.html, transports/. */
+export const distPath = path.join(packageRoot, "dist");
+/** Built-in transport scripts (dist/transports). */
+export const transportsPath = path.join(distPath, "transports");
+/** OpenResty files: conf templates, lua/, default config.lua. */
+export const serverPath = path.join(packageRoot, "server");
+/** Lua modules (server/lua). */
+export const luaPath = path.join(serverPath, "lua");
+/** The built-in frontend: served at /app/, and at / when no --site is given. */
+export const sitePath = path.join(packageRoot, "site");
+/** Default server configuration. */
+export const defaultConfigPath = path.join(serverPath, "config.lua");
+
+export const version = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+
+const BASE = "/butter/";
+const CODECS = ["none", "plain", "xor", "base64"];
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/**
+ * Build the public configuration (what /butter/config.js contains) from a
+ * small static description. Used for deployments without the Lua server.
+ *
+ * @param {{ prefix?: string, codec?: string, transports: Array<{ name: string, url?: string, options?: unknown }>, defaultTransport?: string }} input
+ */
+export function createPublicConfig(input) {
+  const prefix = input.prefix ?? `${BASE}go/`;
+  const codec = input.codec ?? "plain";
+  if (!prefix.startsWith(BASE) || !prefix.endsWith("/") || prefix === BASE) {
+    throw new Error(`prefix must start with ${BASE}, end with "/" and not equal it`);
+  }
+  if (!CODECS.includes(codec)) throw new Error(`codec must be one of ${CODECS.join(", ")}`);
+  if (!Array.isArray(input.transports) || input.transports.length === 0) throw new Error("transports must list at least one transport");
+
+  const seen = new Set();
+  const transports = input.transports.map((entry, i) => {
+    if (!entry || typeof entry.name !== "string" || !NAME.test(entry.name)) throw new Error(`transports[${i}].name is invalid`);
+    if (seen.has(entry.name)) throw new Error(`transport "${entry.name}" is listed twice`);
+    seen.add(entry.name);
+    const out = { name: entry.name, url: entry.url ?? `${BASE}transports/${entry.name}.js` };
+    if (entry.options !== undefined) out.options = entry.options;
+    return out;
+  });
+  const defaultTransport = input.defaultTransport ?? transports[0].name;
+  if (!seen.has(defaultTransport)) throw new Error(`defaultTransport "${defaultTransport}" is not in transports`);
+
+  return {
+    version,
+    prefix,
+    base: BASE,
+    codec,
+    transport: { fetch: `${BASE}fetch`, ws: `${BASE}ws`, cookie: `${BASE}cookie` },
+    client: `${BASE}client.js`,
+    config: `${BASE}config.js`,
+    transports,
+    defaultTransport,
+  };
+}
+
+/** The contents of /butter/config.js for a public configuration. */
+export function createConfigScript(publicConfig) {
+  return `self.__butter$config = ${JSON.stringify(publicConfig)};\n`;
+}
+
+const slash = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "");
+
+/**
+ * Render the OpenResty configuration files.
+ *
+ * @param {{ listen?: string | number, siteRoot?: string, configFile?: string, runtimeDir: string, cacert: string }} options
+ * @returns {{ "nginx.conf": string, "butter-proxy.conf": string, "mime.types": string }}
+ */
+export function renderServerConfig(options) {
+  const values = {
+    LISTEN: String(options.listen ?? 8080),
+    LUA_DIR: slash(luaPath),
+    CONFIG_FILE: slash(options.configFile ?? defaultConfigPath),
+    SITE_ROOT: slash(options.siteRoot ?? sitePath),
+    APP_DIR: slash(sitePath),
+    DIST_DIR: slash(distPath),
+    RUNTIME_DIR: slash(options.runtimeDir),
+    CACERT: slash(options.cacert),
+  };
+  const fill = (template) =>
+    template.replace(/\{\{([A-Z_]+)\}\}/g, (match, key) => {
+      if (!(key in values)) throw new Error(`unknown placeholder ${match}`);
+      return values[key];
+    });
+  const read = (name) => readFileSync(path.join(serverPath, "conf", name), "utf8");
+  return {
+    "nginx.conf": fill(read("nginx.conf.template")),
+    "butter-proxy.conf": fill(read("butter-proxy.conf.template")),
+    "mime.types": read("mime.types"),
+  };
+}
+
+/**
+ * Locate a transport's browser script.
+ *
+ * Transport packages declare it in package.json:
+ *   "butter": { "transport": { "name": "bare", "browser": "dist/bare-transport.js" } }
+ *
+ * @param {string} specifier  package name, or a path to a .js file
+ * @param {string} [from]     directory to resolve packages from (default: cwd)
+ * @returns {{ name: string, file: string, packageName?: string, version?: string }}
+ */
+export function resolveTransport(specifier, from = process.cwd()) {
+  if (/\.m?js$/.test(specifier) && existsSync(path.resolve(from, specifier))) {
+    const file = path.resolve(from, specifier);
+    return { name: path.basename(file).replace(/\.m?js$/, "").replace(/-transport$/, ""), file };
+  }
+  const require = createRequire(path.join(from, "noop.js"));
+  let manifestPath;
+  try {
+    manifestPath = require.resolve(`${specifier}/package.json`);
+  } catch {
+    throw new Error(`cannot find package "${specifier}" (is it installed?)`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const info = manifest.butter && manifest.butter.transport;
+  if (!info || typeof info.name !== "string" || typeof info.browser !== "string") {
+    throw new Error(`${specifier} is not a butter-col transport (package.json has no "butter.transport" field)`);
+  }
+  const file = path.join(path.dirname(manifestPath), info.browser);
+  if (!existsSync(file)) throw new Error(`${specifier}: ${info.browser} does not exist (was the package built?)`);
+  return { name: info.name, file, packageName: manifest.name, version: manifest.version };
+}
+
+/**
+ * Find an OpenResty binary: $OPENRESTY, then .tools/openresty-* (Windows zips
+ * unpacked there) in `cwd` and its parents, then `openresty` on PATH.
+ */
+export function findOpenResty(cwd = process.cwd()) {
+  if (process.env.OPENRESTY) return process.env.OPENRESTY;
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    const tools = path.join(dir, ".tools");
+    if (existsSync(tools)) {
+      const versions = readdirSync(tools).filter((d) => d.startsWith("openresty-")).sort().reverse();
+      for (const version of versions) {
+        for (const exe of ["nginx.exe", "openresty.exe", "bin/openresty"]) {
+          const candidate = path.join(tools, version, exe);
+          if (existsSync(candidate)) return candidate;
+        }
+      }
+    }
+    if (path.dirname(dir) === dir) break;
+  }
+  return "openresty";
+}