From e21a5d634f9699096be38209d726283f0ac9b4a6 Mon Sep 17 00:00:00 2001
From: Dan Chen <dan@djc.me>
Date: Fri, 29 May 2026 23:11:07 -0700
Subject: [PATCH 1/2] test: cover nginx config generator directly

---
 runtime/generate-nginx-config.sh    |   8 +-
 scripts/test-runtime-config.ts      | 425 +-----------------
 tests/generate-nginx-config.test.ts | 642 ++++++++++++++++++++++++++++
 tests/static-csp.contracts.ts       |   4 +-
 4 files changed, 670 insertions(+), 409 deletions(-)
 create mode 100644 tests/generate-nginx-config.test.ts

diff --git a/runtime/generate-nginx-config.sh b/runtime/generate-nginx-config.sh
index a3f5a76..c6902ff 100755
--- a/runtime/generate-nginx-config.sh
+++ b/runtime/generate-nginx-config.sh
@@ -98,12 +98,12 @@ encode_base64() {
   printf '%s' "$1" | base64 | tr -d '\n'
 }
 
-runtime_root="/opt/opencode-web"
+runtime_root="${OPENCODE_WEB_RUNTIME_ROOT:-/opt/opencode-web}"
 public_root="$runtime_root/public"
 runtime_config_root="$runtime_root/runtime-configs"
 runtime_bundle_path="$runtime_root/runtime/runtime-bundle.js"
 nginx_template_path="$runtime_root/config/nginx.conf.template"
-nginx_config_path="/etc/nginx/conf.d/default.conf"
+nginx_config_path="${OPENCODE_WEB_NGINX_CONFIG_PATH:-/etc/nginx/conf.d/default.conf}"
 nginx_servers_marker="# OPENCODE_WEB_GENERATED_SERVERS"
 nginx_listen_port="8080"
 
@@ -220,7 +220,7 @@ server {
   listen $nginx_listen_port;
   listen [::]:$nginx_listen_port;
   server_name $host;
-  root /opt/opencode-web/public;
+  root $public_root;
   index index.html;
 $(write_no_store_headers)
 
@@ -230,7 +230,7 @@ $(write_no_store_headers)
   }
 
   location = /runtime-config.js {
-    alias /opt/opencode-web/runtime-configs/$host.js;
+    alias $runtime_config_root/$host.js;
   }
 
   location ^~ /assets/ {
diff --git a/scripts/test-runtime-config.ts b/scripts/test-runtime-config.ts
index d8725e3..ed04f32 100755
--- a/scripts/test-runtime-config.ts
+++ b/scripts/test-runtime-config.ts
@@ -74,25 +74,6 @@ async function outputFor(args: string[]) {
 	};
 }
 
-async function expectFailure(
-	name: string,
-	expectedMessage: string,
-	args: string[],
-): Promise<void> {
-	console.log(`==> ${name}`);
-	const result = await outputFor(args);
-	if (result.exitCode === 0)
-		throw new Error(`Expected failure, but command succeeded for: ${name}`);
-
-	process.stdout.write(result.output);
-
-	if (!result.output.includes(expectedMessage)) {
-		throw new Error(
-			`Expected message not found for: ${name}\nExpected: ${expectedMessage}`,
-		);
-	}
-}
-
 async function expectSuccess(name: string, args: string[]): Promise<void> {
 	console.log(`==> ${name}`);
 	await run(args);
@@ -111,6 +92,11 @@ async function expectFinalImageLayout(
 			"test -f /opt/opencode-web/config/nginx.conf.template",
 			"test ! -e /opt/opencode-web/config/config",
 			"test -f /opt/opencode-web/public/index.html",
+			"test -d /opt/opencode-web/public/assets",
+			"test -s /opt/opencode-web/public/opencode-web-customizations.css",
+			"test ! -e /opt/opencode-web/public/runtime-config.js",
+			'! grep -F "<style id=\\"opencode-web-customizations\\"" /opt/opencode-web/public/index.html >/dev/null',
+			'grep -F "<link rel=\\"stylesheet\\" href=\\"/opencode-web-customizations.css\\">" /opt/opencode-web/public/index.html >/dev/null',
 			"test -f /opt/opencode-web/runtime/generate-nginx-config.sh",
 			"test -x /docker-entrypoint.d/40-opencode-web.sh",
 			"test -f /opt/opencode-web/runtime/runtime-bundle.js",
@@ -191,14 +177,6 @@ function evaluateRuntimeConfig(
 		);
 }
 
-async function expectGeneratedRuntimeConfigParses(
-	name: string,
-	args: string[],
-): Promise<void> {
-	console.log(`==> ${name}`);
-	new Function(await capture(args));
-}
-
 async function expectGeneratedRuntimeConfigApplies(
 	name: string,
 	expectedTitle: string,
@@ -271,396 +249,37 @@ try {
 		const command = commandIndex === -1 ? [] : args.slice(commandIndex);
 		return ["docker", "run", "--rm", ...dockerOptions, imageTag, ...command];
 	};
-	const entrypoint = ["sh", "-lc", "/docker-entrypoint.d/40-opencode-web.sh"];
-	const generatedConfig = (host: string) =>
-		`test -s /opt/opencode-web/runtime-configs/${host}.js && cat /opt/opencode-web/runtime-configs/${host}.js`;
+	const runtimeEnv = [
+		"-e",
+		"SERVER_1_HOST=web1.opencode.example.com",
+		"-e",
+		"SERVER_1_BACKEND=http://api1.opencode.example.com",
+		"-e",
+		"SERVER_2_HOST=web2.opencode.example.com",
+		"-e",
+		"SERVER_2_BACKEND=http://api2.opencode.example.com",
+	];
 	const multilineEnvValue = "before\nSERVER_9_HOST\nafter";
 
-	await expectFailure(
-		"reject legacy URL-only configuration",
-		"SERVER_1_HOST and SERVER_1_BACKEND are required.",
-		dockerRun(
-			"-e",
-			"SERVER_1_URL=http://api1.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject malformed indexed env names",
-		"Configured backend variable names must use unpadded integer indexes starting at 1. Invalid variable: SERVER_1FOO_HOST.",
-		dockerRun("-e", "SERVER_1FOO_HOST=x", ...entrypoint),
-	);
-	await expectFailure(
-		"reject padded backend indexes",
-		"Configured backend variable names must use unpadded integer indexes starting at 1. Invalid variable: SERVER_01_HOST.",
-		dockerRun("-e", "SERVER_01_HOST=web1.opencode.example.com", ...entrypoint),
-	);
-	await expectFailure(
-		"reject non-contiguous backend indexes",
-		"Configured backend indexes must be contiguous starting at 1. Missing index 2.",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			"-e",
-			"SERVER_3_HOST=web3.opencode.example.com",
-			"-e",
-			"SERVER_3_BACKEND=http://api3.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject missing host",
-		"SERVER_1_HOST is required and must be a hostname-only ASCII DNS name. Use Punycode for IDNs.",
-		dockerRun(
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject missing backend",
-		"SERVER_1_BACKEND is required and must be an absolute http(s) URL.",
-		dockerRun("-e", "SERVER_1_HOST=web1.opencode.example.com", ...entrypoint),
-	);
-	await expectFailure(
-		"reject protocol in host",
-		"SERVER_1_HOST is required and must be a hostname-only ASCII DNS name. Use Punycode for IDNs.",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=https://web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject port in host",
-		"SERVER_1_HOST is required and must be a hostname-only ASCII DNS name. Use Punycode for IDNs.",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com:8080",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject path in host",
-		"SERVER_1_HOST is required and must be a hostname-only ASCII DNS name. Use Punycode for IDNs.",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com/app",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject direct unicode IDN host",
-		"SERVER_1_HOST is required and must be a hostname-only ASCII DNS name. Use Punycode for IDNs.",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=täst.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject duplicate hosts",
-		"Duplicate configured host after normalization: web1.opencode.example.com",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			"-e",
-			"SERVER_2_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_2_BACKEND=http://api2.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject case-variant duplicate hosts",
-		"Duplicate configured host after normalization: web1.opencode.example.com",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=Web1.OpenCode.Example.Com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			"-e",
-			"SERVER_2_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_2_BACKEND=http://api2.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject backend without scheme",
-		"SERVER_1_BACKEND is required and must be an absolute http(s) URL.",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=api1.opencode.example.com",
-			...entrypoint,
-		),
-	);
-	await expectFailure(
-		"reject backend with empty host after scheme",
-		"SERVER_1_BACKEND is required and must be an absolute http(s) URL.",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://",
-			...entrypoint,
-		),
-	);
-
 	await expectFinalImageLayout(
-		"final image layout is sane",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-		),
+		"final image layout and permissions are sane",
+		dockerRun(...runtimeEnv),
 	);
 	await expectSuccess(
-		"ignore multiline env values while scanning backend vars",
+		"entrypoint ignores multiline unrelated env values on Alpine",
 		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
+			...runtimeEnv,
 			"-e",
 			`UNRELATED_MULTILINE=${multilineEnvValue}`,
 			"sh",
 			"-lc",
-			"/docker-entrypoint.d/40-opencode-web.sh && test -s /opt/opencode-web/runtime-configs/web1.opencode.example.com.js && test ! -e /opt/opencode-web/public/runtime-config.js",
-		),
-	);
-	await expectSuccess(
-		"clean stale generated runtime config files",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			"sh",
-			"-lc",
-			"touch /opt/opencode-web/runtime-configs/stale.js && /docker-entrypoint.d/40-opencode-web.sh && test -d /opt/opencode-web/runtime-configs && test ! -e /opt/opencode-web/runtime-configs/stale.js && test -s /opt/opencode-web/runtime-configs/web1.opencode.example.com.js",
-		),
-	);
-	await expectSuccess(
-		"generate valid host-based runtime payloads",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=https://api1.opencode.example.com",
-			"-e",
-			"SERVER_1_NAME=Server 1",
-			"-e",
-			"SERVER_1_APP_TITLE=Server 1 Web",
-			"-e",
-			"SERVER_2_HOST=web2.opencode.example.com",
-			"-e",
-			"SERVER_2_BACKEND=https://api2.opencode.example.com/",
-			"-e",
-			"SERVER_2_APP_TITLE=Server 2 Web",
-			"sh",
-			"-lc",
-			'/docker-entrypoint.d/40-opencode-web.sh && test -s /opt/opencode-web/runtime-configs/web1.opencode.example.com.js && test -s /opt/opencode-web/runtime-configs/web2.opencode.example.com.js && test -s /etc/nginx/conf.d/default.conf && test ! -e /opt/opencode-web/public/runtime-config.js && test -d /opt/opencode-web/public/assets && test -s /opt/opencode-web/public/opencode-web-customizations.css && ! grep -F "<style id=\\"opencode-web-customizations\\"" /opt/opencode-web/public/index.html >/dev/null && grep -F "<link rel=\\"stylesheet\\" href=\\"/opencode-web-customizations.css\\">" /opt/opencode-web/public/index.html >/dev/null',
-		),
-	);
-	await expectSuccess(
-		"runtime config generation is idempotent",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			"-e",
-			"SERVER_2_HOST=web2.opencode.example.com",
-			"-e",
-			"SERVER_2_BACKEND=http://api2.opencode.example.com",
-			"sh",
-			"-lc",
-			'/docker-entrypoint.d/40-opencode-web.sh && test "$(grep -c "server_name web" /etc/nginx/conf.d/default.conf)" -eq 2',
-		),
-	);
-
-	await expectGeneratedRuntimeConfigApplies(
-		"server 1 runtime-config applies only server 1",
-		"Server 1 Web",
-		"https://api1.opencode.example.com",
-		"https://api1.opencode.example.com",
-		'[{"url":"https://api1.opencode.example.com","name":"Server 1"}]',
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=https://api1.opencode.example.com",
-			"-e",
-			"SERVER_1_NAME=Server 1",
-			"-e",
-			"SERVER_1_APP_TITLE=Server 1 Web",
-			"-e",
-			"SERVER_2_HOST=web2.opencode.example.com",
-			"-e",
-			"SERVER_2_BACKEND=https://api2.opencode.example.com/",
-			"sh",
-			"-lc",
-			`/docker-entrypoint.d/40-opencode-web.sh && ${generatedConfig("web1.opencode.example.com")}`,
-		),
-	);
-	await expectGeneratedRuntimeConfigApplies(
-		"server 2 runtime-config applies only server 2",
-		"Server 2 Web",
-		"https://api2.opencode.example.com",
-		"https://api2.opencode.example.com",
-		'[{"url":"https://api2.opencode.example.com","name":"Server 2"}]',
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=https://api1.opencode.example.com",
-			"-e",
-			"SERVER_1_NAME=Server 1",
-			"-e",
-			"SERVER_2_HOST=web2.opencode.example.com",
-			"-e",
-			"SERVER_2_BACKEND=https://api2.opencode.example.com/",
-			"-e",
-			"SERVER_2_NAME=Server 2",
-			"-e",
-			"SERVER_1_APP_TITLE=Server 1 Web",
-			"-e",
-			"SERVER_2_APP_TITLE=Server 2 Web",
-			"sh",
-			"-lc",
-			`/docker-entrypoint.d/40-opencode-web.sh && ${generatedConfig("web2.opencode.example.com")}`,
-		),
-	);
-	await expectGeneratedRuntimeConfigApplies(
-		"generated runtime-config preserves unicode metadata",
-		"你好 OpenCode",
-		"https://api1.opencode.example.com",
-		"https://api1.opencode.example.com",
-		'[{"url":"https://api1.opencode.example.com","name":"München"}]',
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=xn--tst-qla.example.com",
-			"-e",
-			"SERVER_1_BACKEND=https://api1.opencode.example.com",
-			"-e",
-			"SERVER_1_NAME=München",
-			"-e",
-			"SERVER_1_APP_TITLE=你好 OpenCode",
-			"sh",
-			"-lc",
-			`/docker-entrypoint.d/40-opencode-web.sh && ${generatedConfig("xn--tst-qla.example.com")}`,
-		),
-	);
-	await expectGeneratedRuntimeConfigParses(
-		"generated runtime-config.js parses as JavaScript",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=https://api1.opencode.example.com",
-			"-e",
-			"SERVER_1_NAME=Server 1",
-			"-e",
-			"SERVER_1_APP_TITLE=Hosted OpenCode",
-			"sh",
-			"-lc",
-			`/docker-entrypoint.d/40-opencode-web.sh && ${generatedConfig("web1.opencode.example.com")}`,
-		),
-	);
-	await expectGeneratedRuntimeConfigApplies(
-		"normalizes uppercase scheme and hostname to lowercase",
-		"OpenCode",
-		"https://api1.opencode.example.com",
-		"https://api1.opencode.example.com",
-		'[{"url":"https://api1.opencode.example.com","name":""}]',
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=WEB1.OPENCODE.EXAMPLE.COM",
-			"-e",
-			"SERVER_1_BACKEND=HTTPS://API1.OPENCODE.EXAMPLE.COM",
-			"sh",
-			"-lc",
-			`/docker-entrypoint.d/40-opencode-web.sh && ${generatedConfig("web1.opencode.example.com")}`,
-		),
-	);
-	await expectGeneratedRuntimeConfigApplies(
-		"preserves URL path case while normalizing scheme and host",
-		"OpenCode",
-		"https://api.opencode.example.com/pAtH",
-		"https://api.opencode.example.com/pAtH",
-		'[{"url":"https://api.opencode.example.com/pAtH","name":""}]',
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=HTTPS://API.OPENCODE.EXAMPLE.COM/pAtH",
-			"sh",
-			"-lc",
-			`/docker-entrypoint.d/40-opencode-web.sh && ${generatedConfig("web1.opencode.example.com")}`,
-		),
-	);
-	await expectGeneratedRuntimeConfigApplies(
-		"preserves port while normalizing scheme and host",
-		"OpenCode",
-		"http://api.opencode.example.com:8080",
-		"http://api.opencode.example.com:8080",
-		'[{"url":"http://api.opencode.example.com:8080","name":""}]',
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=HTTP://API.OPENCODE.EXAMPLE.COM:8080",
-			"sh",
-			"-lc",
-			`/docker-entrypoint.d/40-opencode-web.sh && ${generatedConfig("web1.opencode.example.com")}`,
-		),
-	);
-	await expectSuccess(
-		"allow duplicate backend URLs across hosts",
-		dockerRun(
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api.opencode.example.com",
-			"-e",
-			"SERVER_2_HOST=web2.opencode.example.com",
-			"-e",
-			"SERVER_2_BACKEND=http://api.opencode.example.com/",
-			"sh",
-			"-lc",
-			"/docker-entrypoint.d/40-opencode-web.sh && test -s /opt/opencode-web/runtime-configs/web1.opencode.example.com.js && test -s /opt/opencode-web/runtime-configs/web2.opencode.example.com.js",
+			"/docker-entrypoint.d/40-opencode-web.sh && test -s /opt/opencode-web/runtime-configs/web1.opencode.example.com.js && test -s /etc/nginx/conf.d/default.conf",
 		),
 	);
 
 	const containerId = await withNginxContainer(
 		"nginx starts through official entrypoint",
-		[
-			"-e",
-			"SERVER_1_HOST=web1.opencode.example.com",
-			"-e",
-			"SERVER_1_BACKEND=http://api1.opencode.example.com",
-			"-e",
-			"SERVER_2_HOST=web2.opencode.example.com",
-			"-e",
-			"SERVER_2_BACKEND=http://api2.opencode.example.com",
-			imageTag,
-		],
+		[...runtimeEnv, imageTag],
 	);
 	try {
 		await expectGeneratedRuntimeConfigApplies(
@@ -770,7 +389,7 @@ try {
 		await stopNginxContainer(containerId);
 	}
 
-	console.log("==> All runtime-config regression checks passed");
+	console.log("==> Runtime-config Docker smoke checks passed");
 } catch (error) {
 	console.error(error instanceof Error ? error.message : String(error));
 	process.exit(1);
diff --git a/tests/generate-nginx-config.test.ts b/tests/generate-nginx-config.test.ts
new file mode 100644
index 0000000..0c797da
--- /dev/null
+++ b/tests/generate-nginx-config.test.ts
@@ -0,0 +1,642 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import {
+	copyFile,
+	mkdir,
+	mkdtemp,
+	readFile,
+	rm,
+	writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import vm from "node:vm";
+import { buildRuntimeBundle } from "../build/transpile-runtime";
+import { makeTempDir } from "./temp-dir";
+
+const repoRoot = fileURLToPath(new URL("..", import.meta.url));
+const generatorPath = path.join(repoRoot, "runtime/generate-nginx-config.sh");
+const templatePath = path.join(repoRoot, "config/nginx.conf.template");
+const serverStoreKey = "opencode.global.dat:server";
+const defaultServerUrlKey = "opencode.settings.dat:defaultServerUrl";
+const noStoreCacheControl = "no-store, no-cache, must-revalidate";
+const immutableCacheControl = "public, max-age=31536000, immutable";
+const staticWebCsp =
+	"default-src 'self'; base-uri 'self'; connect-src * data:; font-src 'self' data:; frame-ancestors 'none'; img-src 'self' data: https:; media-src 'self' data:; object-src 'none'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'";
+
+type RuntimeRoot = {
+	root: string;
+	configPath: string;
+	runtimeConfigPath: (host: string) => string;
+};
+
+type GeneratorResult = {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+	output: string;
+};
+
+type ValidationCase = {
+	name: string;
+	env: Record<string, string>;
+	message: string;
+};
+
+let bundleDir: string | undefined;
+let runtimeBundleSourcePromise: Promise<string> | undefined;
+
+async function loadRuntimeBundleSource(): Promise<string> {
+	runtimeBundleSourcePromise ??= (async () => {
+		bundleDir = await mkdirTemp("runtime-bundle-generate-test-");
+		await buildRuntimeBundle(bundleDir);
+		return readFile(path.join(bundleDir, "runtime-bundle.js"), "utf8");
+	})();
+
+	return runtimeBundleSourcePromise;
+}
+
+async function mkdirTemp(prefix: string): Promise<string> {
+	return mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+async function makeRuntimeRoot(): Promise<RuntimeRoot> {
+	const root = await makeTempDir("generate-nginx-config-");
+	await mkdir(path.join(root, "public"), { recursive: true });
+	await mkdir(path.join(root, "runtime"), { recursive: true });
+	await mkdir(path.join(root, "config"), { recursive: true });
+	await mkdir(path.join(root, "runtime-configs"), { recursive: true });
+	await writeFile(path.join(root, "public/index.html"), "<!doctype html>\n");
+	await writeFile(
+		path.join(root, "runtime/runtime-bundle.js"),
+		await loadRuntimeBundleSource(),
+	);
+	await copyFile(templatePath, path.join(root, "config/nginx.conf.template"));
+
+	return {
+		root,
+		configPath: path.join(root, "generated-nginx.conf"),
+		runtimeConfigPath: (host) =>
+			path.join(root, "runtime-configs", `${host}.js`),
+	};
+}
+
+async function runGenerator(
+	fixture: RuntimeRoot,
+	input: { env?: Record<string, string> } = {},
+): Promise<GeneratorResult> {
+	const args = [
+		"env",
+		"-i",
+		`PATH=${process.env.PATH ?? ""}`,
+		`OPENCODE_WEB_RUNTIME_ROOT=${fixture.root}`,
+		`OPENCODE_WEB_NGINX_CONFIG_PATH=${fixture.configPath}`,
+	];
+
+	for (const [name, value] of Object.entries(input.env ?? {})) {
+		args.push(`${name}=${value}`);
+	}
+	args.push("sh", generatorPath);
+
+	const child = Bun.spawn(args, {
+		stderr: "pipe",
+		stdout: "pipe",
+	});
+	const [exitCode, stdout, stderr] = await Promise.all([
+		child.exited,
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+	]);
+
+	return {
+		exitCode,
+		stdout,
+		stderr,
+		output: `${stdout}${stderr}`,
+	};
+}
+
+function assertSuccess(result: GeneratorResult): void {
+	if (result.exitCode !== 0) {
+		throw new Error(`Expected generator to succeed, got:\n${result.output}`);
+	}
+}
+
+function expectedServerBlock(input: { root: string; host: string }): string {
+	return [
+		"server {",
+		"  listen 8080;",
+		"  listen [::]:8080;",
+		`  server_name ${input.host};`,
+		`  root ${input.root}/public;`,
+		"  index index.html;",
+		`  add_header Cache-Control "${noStoreCacheControl}" always;`,
+		`  add_header Content-Security-Policy "${staticWebCsp}" always;`,
+		"",
+		"  location = /health {",
+		"    default_type text/plain;",
+		'    return 200 "ok\\n";',
+		"  }",
+		"",
+		"  location = /runtime-config.js {",
+		`    alias ${input.root}/runtime-configs/${input.host}.js;`,
+		"  }",
+		"",
+		"  location ^~ /assets/ {",
+		`    add_header Cache-Control "${immutableCacheControl}" always;`,
+		`    add_header Content-Security-Policy "${staticWebCsp}" always;`,
+		"    try_files $uri =404;",
+		"  }",
+		"",
+		"  location ~ \\.[^/]+$ {",
+		"    try_files $uri =404;",
+		"  }",
+		"",
+		"  location / {",
+		"    try_files $uri $uri/ /index.html;",
+		"  }",
+		"}",
+	].join("\n");
+}
+
+function countMatches(source: string, pattern: RegExp): number {
+	return [...source.matchAll(pattern)].length;
+}
+
+function evaluateRuntimeConfig(
+	source: string,
+	expected: { title: string; backendUrl: string; name: string },
+): void {
+	const storage = new Map<string, string>();
+	const context = {
+		Buffer,
+		JSON,
+		TextDecoder,
+		Uint8Array,
+		atob: (value: string) => Buffer.from(value, "base64").toString("binary"),
+		console,
+		document: { title: "OpenCode" },
+		location: { origin: "http://frontend.opencode.example.com" },
+		localStorage: {
+			getItem: (key: string) => (storage.has(key) ? storage.get(key)! : null),
+			setItem: (key: string, value: string) => storage.set(key, value),
+			removeItem: (key: string) => storage.delete(key),
+		},
+		window: {} as { __OPENCODE_SERVER_URL?: string },
+	};
+
+	expect(() => new Function(source)).not.toThrow();
+	vm.runInNewContext(source, context, { timeout: 1000 });
+
+	const savedStateRaw = storage.get(serverStoreKey);
+	expect(savedStateRaw).toBeTruthy();
+	const savedState = JSON.parse(savedStateRaw!) as {
+		list: Array<{
+			http?: { url?: string };
+			url?: string;
+			displayName?: string;
+		}>;
+	};
+
+	expect(context.document.title).toBe(expected.title);
+	expect(context.window.__OPENCODE_SERVER_URL).toBe(expected.backendUrl);
+	expect(storage.get(defaultServerUrlKey)).toBe(expected.backendUrl);
+	expect(
+		savedState.list.map((item) => ({
+			url: item.http?.url ?? item.url,
+			name: item.displayName ?? "",
+		})),
+	).toEqual([{ url: expected.backendUrl, name: expected.name }]);
+}
+
+async function expectFailure(
+	env: Record<string, string>,
+	expectedMessage: string,
+): Promise<void> {
+	const fixture = await makeRuntimeRoot();
+	const result = await runGenerator(fixture, { env });
+
+	expect(result.exitCode).not.toBe(0);
+	expect(result.output).toContain(expectedMessage);
+}
+
+afterAll(async () => {
+	if (!bundleDir) return;
+	await rm(bundleDir, { recursive: true, force: true });
+});
+
+describe("generate-nginx-config", () => {
+	const hostError =
+		"SERVER_1_HOST is required and must be a hostname-only ASCII DNS name. Use Punycode for IDNs.";
+	const backendError =
+		"SERVER_1_BACKEND is required and must be an absolute http(s) URL.";
+	const validHost = "web1.opencode.example.com";
+	const validBackend = "http://api1.opencode.example.com";
+
+	const validationCases: ValidationCase[] = [
+		{
+			name: "missing SERVER_1_HOST and SERVER_1_BACKEND",
+			env: {},
+			message: "SERVER_1_HOST and SERVER_1_BACKEND are required.",
+		},
+		{
+			name: "legacy URL-only configuration",
+			env: { SERVER_1_URL: validBackend },
+			message: "SERVER_1_HOST and SERVER_1_BACKEND are required.",
+		},
+		{
+			name: "malformed indexed env names",
+			env: { SERVER_1FOO_HOST: "x" },
+			message:
+				"Configured backend variable names must use unpadded integer indexes starting at 1. Invalid variable: SERVER_1FOO_HOST.",
+		},
+		{
+			name: "padded indexes",
+			env: { SERVER_01_HOST: validHost },
+			message:
+				"Configured backend variable names must use unpadded integer indexes starting at 1. Invalid variable: SERVER_01_HOST.",
+		},
+		{
+			name: "non-contiguous indexes",
+			env: {
+				SERVER_1_HOST: validHost,
+				SERVER_1_BACKEND: validBackend,
+				SERVER_3_HOST: "web3.opencode.example.com",
+				SERVER_3_BACKEND: "http://api3.opencode.example.com",
+			},
+			message:
+				"Configured backend indexes must be contiguous starting at 1. Missing index 2.",
+		},
+		{
+			name: "missing host",
+			env: { SERVER_1_BACKEND: validBackend },
+			message: hostError,
+		},
+		{
+			name: "missing backend",
+			env: { SERVER_1_HOST: validHost },
+			message: backendError,
+		},
+		{
+			name: "host with protocol",
+			env: {
+				SERVER_1_HOST: `https://${validHost}`,
+				SERVER_1_BACKEND: validBackend,
+			},
+			message: hostError,
+		},
+		{
+			name: "host with port",
+			env: {
+				SERVER_1_HOST: `${validHost}:8080`,
+				SERVER_1_BACKEND: validBackend,
+			},
+			message: hostError,
+		},
+		{
+			name: "host with path",
+			env: {
+				SERVER_1_HOST: `${validHost}/app`,
+				SERVER_1_BACKEND: validBackend,
+			},
+			message: hostError,
+		},
+		{
+			name: "wildcard host",
+			env: {
+				SERVER_1_HOST: "*.opencode.example.com",
+				SERVER_1_BACKEND: validBackend,
+			},
+			message: hostError,
+		},
+		{
+			name: "host with whitespace",
+			env: {
+				SERVER_1_HOST: "web 1.opencode.example.com",
+				SERVER_1_BACKEND: validBackend,
+			},
+			message: hostError,
+		},
+		{
+			name: "direct unicode IDN host",
+			env: {
+				SERVER_1_HOST: "t\u00e4st.example.com",
+				SERVER_1_BACKEND: validBackend,
+			},
+			message: hostError,
+		},
+		{
+			name: "duplicate normalized hosts",
+			env: {
+				SERVER_1_HOST: validHost,
+				SERVER_1_BACKEND: validBackend,
+				SERVER_2_HOST: validHost,
+				SERVER_2_BACKEND: "http://api2.opencode.example.com",
+			},
+			message:
+				"Duplicate configured host after normalization: web1.opencode.example.com",
+		},
+		{
+			name: "case-variant duplicate hosts",
+			env: {
+				SERVER_1_HOST: "Web1.OpenCode.Example.Com",
+				SERVER_1_BACKEND: validBackend,
+				SERVER_2_HOST: validHost,
+				SERVER_2_BACKEND: "http://api2.opencode.example.com",
+			},
+			message:
+				"Duplicate configured host after normalization: web1.opencode.example.com",
+		},
+		{
+			name: "backend without scheme",
+			env: {
+				SERVER_1_HOST: validHost,
+				SERVER_1_BACKEND: "api1.opencode.example.com",
+			},
+			message: backendError,
+		},
+		{
+			name: "backend with empty host after scheme",
+			env: {
+				SERVER_1_HOST: validHost,
+				SERVER_1_BACKEND: "http://",
+			},
+			message: backendError,
+		},
+	];
+
+	for (const validationCase of validationCases) {
+		test(`rejects ${validationCase.name}`, async () => {
+			await expectFailure(validationCase.env, validationCase.message);
+		});
+	}
+
+	test("generates host-specific runtime payloads and nginx server blocks", async () => {
+		const fixture = await makeRuntimeRoot();
+		const result = await runGenerator(fixture, {
+			env: {
+				SERVER_1_HOST: "Web1.OpenCode.Example.Com",
+				SERVER_1_BACKEND: "HTTPS://API1.OPENCODE.EXAMPLE.COM",
+				SERVER_1_NAME: "Server 1",
+				SERVER_1_APP_TITLE: "Server 1 Web",
+				SERVER_2_HOST: "web2.opencode.example.com",
+				SERVER_2_BACKEND: "https://api2.opencode.example.com/",
+				SERVER_2_NAME: "Server 2",
+				SERVER_2_APP_TITLE: "Server 2 Web",
+			},
+		});
+
+		assertSuccess(result);
+		expect(result.stdout).toBe("");
+		expect(result.stderr).toBe("");
+		expect(
+			await Bun.file(
+				fixture.runtimeConfigPath("web1.opencode.example.com"),
+			).exists(),
+		).toBe(true);
+		expect(
+			await Bun.file(
+				fixture.runtimeConfigPath("web2.opencode.example.com"),
+			).exists(),
+		).toBe(true);
+		expect(
+			await Bun.file(
+				path.join(fixture.root, "public/runtime-config.js"),
+			).exists(),
+		).toBe(false);
+
+		const nginxConfig = await readFile(fixture.configPath, "utf8");
+		expect(nginxConfig).not.toContain("# OPENCODE_WEB_GENERATED_SERVERS");
+		expect(nginxConfig).toContain("listen 8080 default_server;");
+		expect(nginxConfig).toContain("listen [::]:8080 default_server;");
+		expect(nginxConfig).toContain(
+			expectedServerBlock({
+				root: fixture.root,
+				host: "web1.opencode.example.com",
+			}),
+		);
+		expect(nginxConfig).toContain(
+			expectedServerBlock({
+				root: fixture.root,
+				host: "web2.opencode.example.com",
+			}),
+		);
+		expect(
+			countMatches(nginxConfig, /server_name web\d\.opencode\.example\.com;/g),
+		).toBe(2);
+
+		evaluateRuntimeConfig(
+			await readFile(
+				fixture.runtimeConfigPath("web1.opencode.example.com"),
+				"utf8",
+			),
+			{
+				title: "Server 1 Web",
+				backendUrl: "https://api1.opencode.example.com",
+				name: "Server 1",
+			},
+		);
+		evaluateRuntimeConfig(
+			await readFile(
+				fixture.runtimeConfigPath("web2.opencode.example.com"),
+				"utf8",
+			),
+			{
+				title: "Server 2 Web",
+				backendUrl: "https://api2.opencode.example.com",
+				name: "Server 2",
+			},
+		);
+	});
+
+	for (const normalizationCase of [
+		{
+			name: "lowercases uppercase scheme and host",
+			backend: "HTTPS://API1.OPENCODE.EXAMPLE.COM",
+			expected: "https://api1.opencode.example.com",
+		},
+		{
+			name: "preserves URL path case",
+			backend: "HTTPS://API.OPENCODE.EXAMPLE.COM/pAtH",
+			expected: "https://api.opencode.example.com/pAtH",
+		},
+		{
+			name: "preserves port",
+			backend: "HTTP://API.OPENCODE.EXAMPLE.COM:8080",
+			expected: "http://api.opencode.example.com:8080",
+		},
+		{
+			name: "removes trailing slash",
+			backend: "https://API.OPENCODE.EXAMPLE.COM/path/",
+			expected: "https://api.opencode.example.com/path",
+		},
+	]) {
+		test(`normalizes backend URL: ${normalizationCase.name}`, async () => {
+			const fixture = await makeRuntimeRoot();
+			const result = await runGenerator(fixture, {
+				env: {
+					SERVER_1_HOST: validHost,
+					SERVER_1_BACKEND: normalizationCase.backend,
+				},
+			});
+
+			assertSuccess(result);
+			evaluateRuntimeConfig(
+				await readFile(fixture.runtimeConfigPath(validHost), "utf8"),
+				{
+					title: "OpenCode",
+					backendUrl: normalizationCase.expected,
+					name: "",
+				},
+			);
+		});
+	}
+
+	test("allows duplicate backend URLs across hosts", async () => {
+		const fixture = await makeRuntimeRoot();
+		const result = await runGenerator(fixture, {
+			env: {
+				SERVER_1_HOST: validHost,
+				SERVER_1_BACKEND: "http://api.opencode.example.com",
+				SERVER_2_HOST: "web2.opencode.example.com",
+				SERVER_2_BACKEND: "http://api.opencode.example.com/",
+			},
+		});
+
+		assertSuccess(result);
+		evaluateRuntimeConfig(
+			await readFile(fixture.runtimeConfigPath(validHost), "utf8"),
+			{
+				title: "OpenCode",
+				backendUrl: "http://api.opencode.example.com",
+				name: "",
+			},
+		);
+		evaluateRuntimeConfig(
+			await readFile(
+				fixture.runtimeConfigPath("web2.opencode.example.com"),
+				"utf8",
+			),
+			{
+				title: "OpenCode",
+				backendUrl: "http://api.opencode.example.com",
+				name: "",
+			},
+		);
+	});
+
+	test("preserves unicode runtime metadata for Punycode hosts", async () => {
+		const fixture = await makeRuntimeRoot();
+		const result = await runGenerator(fixture, {
+			env: {
+				SERVER_1_HOST: "xn--tst-qla.example.com",
+				SERVER_1_BACKEND: "https://api1.opencode.example.com",
+				SERVER_1_NAME: "M\u00fcnchen",
+				SERVER_1_APP_TITLE: "\u4f60\u597d OpenCode",
+			},
+		});
+
+		assertSuccess(result);
+		evaluateRuntimeConfig(
+			await readFile(
+				fixture.runtimeConfigPath("xn--tst-qla.example.com"),
+				"utf8",
+			),
+			{
+				title: "\u4f60\u597d OpenCode",
+				backendUrl: "https://api1.opencode.example.com",
+				name: "M\u00fcnchen",
+			},
+		);
+	});
+
+	test("removes stale runtime configs and remains idempotent", async () => {
+		const fixture = await makeRuntimeRoot();
+		const stalePath = fixture.runtimeConfigPath("stale");
+		const env = {
+			SERVER_1_HOST: validHost,
+			SERVER_1_BACKEND: validBackend,
+			SERVER_2_HOST: "web2.opencode.example.com",
+			SERVER_2_BACKEND: "http://api2.opencode.example.com",
+		};
+
+		await writeFile(stalePath, "stale");
+		assertSuccess(await runGenerator(fixture, { env }));
+		expect(await Bun.file(stalePath).exists()).toBe(false);
+		assertSuccess(await runGenerator(fixture, { env }));
+
+		const nginxConfig = await readFile(fixture.configPath, "utf8");
+		expect(
+			countMatches(nginxConfig, /server_name web\d\.opencode\.example\.com;/g),
+		).toBe(2);
+	});
+
+	test("ignores multiline unrelated env values while scanning backend vars", async () => {
+		const fixture = await makeRuntimeRoot();
+		const result = await runGenerator(fixture, {
+			env: {
+				SERVER_1_HOST: validHost,
+				SERVER_1_BACKEND: validBackend,
+				UNRELATED_MULTILINE: "before\nSERVER_9_HOST\nafter",
+			},
+		});
+
+		assertSuccess(result);
+		expect(await Bun.file(fixture.runtimeConfigPath(validHost)).exists()).toBe(
+			true,
+		);
+	});
+
+	for (const prerequisiteCase of [
+		{
+			name: "runtime bundle",
+			removePath: (fixture: RuntimeRoot) =>
+				path.join(fixture.root, "runtime/runtime-bundle.js"),
+			message: (fixture: RuntimeRoot) =>
+				`Missing runtime bundle at ${path.join(fixture.root, "runtime/runtime-bundle.js")}`,
+		},
+		{
+			name: "nginx config template",
+			removePath: (fixture: RuntimeRoot) =>
+				path.join(fixture.root, "config/nginx.conf.template"),
+			message: (fixture: RuntimeRoot) =>
+				`Missing nginx config template at ${path.join(fixture.root, "config/nginx.conf.template")}`,
+		},
+		{
+			name: "public root",
+			removePath: (fixture: RuntimeRoot) => path.join(fixture.root, "public"),
+			message: (fixture: RuntimeRoot) =>
+				`Missing public root at ${path.join(fixture.root, "public")}`,
+		},
+	]) {
+		test(`fails when ${prerequisiteCase.name} is missing`, async () => {
+			const fixture = await makeRuntimeRoot();
+			await rm(prerequisiteCase.removePath(fixture), {
+				recursive: true,
+				force: true,
+			});
+			const result = await runGenerator(fixture, {
+				env: { SERVER_1_HOST: validHost, SERVER_1_BACKEND: validBackend },
+			});
+
+			expect(result.exitCode).not.toBe(0);
+			expect(result.output).toContain(prerequisiteCase.message(fixture));
+		});
+	}
+
+	test("fails when nginx template is missing the generated server marker", async () => {
+		const fixture = await makeRuntimeRoot();
+		await writeFile(
+			path.join(fixture.root, "config/nginx.conf.template"),
+			"server {}\n",
+		);
+		const result = await runGenerator(fixture, {
+			env: { SERVER_1_HOST: validHost, SERVER_1_BACKEND: validBackend },
+		});
+
+		expect(result.exitCode).not.toBe(0);
+		expect(result.output).toContain(
+			`Missing nginx server marker in ${path.join(fixture.root, "config/nginx.conf.template")}`,
+		);
+	});
+});
diff --git a/tests/static-csp.contracts.ts b/tests/static-csp.contracts.ts
index 39a8414..37f2144 100644
--- a/tests/static-csp.contracts.ts
+++ b/tests/static-csp.contracts.ts
@@ -268,8 +268,8 @@ export const staticCspContracts: Contract[] = [
 			),
 			match(
 				"runtimeGenerator",
-				/alias \/opt\/opencode-web\/runtime-configs\/\$host\.js;/,
-				"expected generated /runtime-config.js to alias the per-host runtime config",
+				/alias \$runtime_config_root\/\$host\.js;/,
+				"expected generated /runtime-config.js to alias the configured per-host runtime config root",
 			),
 			match(
 				"runtimeGenerator",

From dfa380b98a3b93440554719e5121c9112e1e49bc Mon Sep 17 00:00:00 2001
From: Dan Chen <dan@djc.me>
Date: Fri, 29 May 2026 23:17:35 -0700
Subject: [PATCH 2/2] docs: refine AGENTS.md wording and remove redundant
 focused-test line

---
 AGENTS.md | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 99863c6..6619c20 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,22 +1,22 @@
 ## Scope
 
-- This repo owns the static-web wrapper only. `opencode/` is an upstream git submodule; do not edit files under it here. The only allowed upstream change is moving the submodule pointer.
+- This repo owns the static-web wrapper only. `opencode/` is an upstream git submodule; do not edit files under it here except to move the submodule pointer.
 - Wrapper-owned code lives in `build/`, `runtime/`, `config/`, `scripts/`, `tests/`, and root Docker/CI/package config.
 - If you must inspect upstream code, read the closest `AGENTS.md` inside `opencode/` first; upstream's default branch is `dev`, not `main`.
 
 ## Runtime Wiring
 
-- `Dockerfile` is the real integration path: it installs the filtered upstream app workspace, patches `opencode/packages/app/src/entry.tsx` with `build/patch-upstream-app-source.ts`, builds `opencode/packages/app`, copies wrapper sources, runs `build/check-runtime-config-compat.ts`, bundles `runtime/index.ts`, prepares `opencode/packages/app/dist`, then serves it with nginx.
+- `Dockerfile` is the integration source of truth: it installs only the filtered upstream app workspace, patches `opencode/packages/app/src/entry.tsx`, builds `opencode/packages/app`, runs `build/check-runtime-config-compat.ts`, bundles `runtime/index.ts`, prepares `opencode/packages/app/dist`, then serves it with nginx.
 - `runtime/generate-nginx-config.sh` is the runtime generation source of truth. It runs as `/docker-entrypoint.d/40-opencode-web.sh` under Alpine `/bin/sh`, requires contiguous unpadded indexes starting at `1`, normalizes hostnames/backend URLs, writes per-host configs under `/opt/opencode-web/runtime-configs/<host>.js`, and regenerates nginx config from `config/nginx.conf.template`.
 - `runtime/runtime-config-core.ts` is the browser bootstrap: it replaces the persisted server list and default server URL with the injected backend for that host, prunes other servers/credentials, and removes legacy `server.v3`.
 - `build/prepare-static-web.ts` injects `/runtime-config.js` and writes `opencode-web-customizations.css` from `build/customization-css.ts`; source-level URL injection belongs in `build/patch-upstream-app-source.ts` before the upstream app build.
-- `config/nginx.conf.template` is the base nginx cache/CSP contract: unmatched hosts return 404 except `/health`, configured hosts are appended by the generator, only `/assets/` is immutable, and all other configured-host responses stay `no-store` with `add_header ... always`.
+- `config/nginx.conf.template` plus the generator define the nginx cache/CSP/routing contract: unmatched hosts return 404 except `/health`, configured host routes fall back to `/index.html`, only `/assets/` is immutable, and all other configured-host responses stay `no-store` with `add_header ... always`.
 
 ## Compatibility Contracts
 
-- Root `bun test` runs only `./tests` because root `bunfig.toml` sets `[test].root = "./tests"`.
+- Root `bun test` runs only `./tests` because root `bunfig.toml` sets `[test].root = "./tests"`; use `bun test tests/<name>.test.ts` for a focused root test.
 - `tests/*.contracts.ts` encode every wrapper assumption about upstream app internals, runtime persistence, CSS selectors, and nginx CSP/cache behavior. If upstream changes break the wrapper, update the contract and wrapper code together.
-- `bun run test:compat` is the same upstream-compat guard used during `docker build`; keep it free of extra root-only dependencies because Docker invokes `bun ./build/check-runtime-config-compat.ts` without installing the root package.
+- `bun run test:compat` is the upstream-compat guard used during `docker build`; keep it free of root-only dependencies because Docker invokes `bun ./build/check-runtime-config-compat.ts` without installing the root package.
 - CSP/cache headers are intentionally duplicated in `config/nginx.conf.template` and `runtime/generate-nginx-config.sh`; keep them in sync.
 
 ## Commands
@@ -29,7 +29,6 @@
 - Upstream compatibility check only: `bun run test:compat`
 - Runtime bundle only: `bun run build:runtime`
 - Static web preparation only, after the upstream app dist exists: `bun run build:prepare-static -- opencode/packages/app/dist`
-- Focused root tests: `bun test tests/<name>.test.ts`, for example `bun test tests/compatibility-contracts.test.ts`
 - Runtime/image regression check: `bun run test:runtime-config -- --build`; without `--build`, the script expects an existing image tag, defaulting to `opencode-web-docker`.
 - End-to-end build: `bun run docker:build` or `docker build -t opencode-web-docker .`
 - Docker-equivalent upstream app build: `bun install --cwd opencode --filter @opencode-ai/app --frozen-lockfile --ignore-scripts` then `bun ./build/patch-upstream-app-source.ts ./opencode/packages/app/src` then `OPENCODE_CHANNEL=prod bun run --cwd opencode/packages/app build -- --sourcemap false`
@@ -46,4 +45,4 @@
 - Shell scripts are `/bin/sh`/Alpine-compatible; keep `runtime/generate-nginx-config.sh` env scanning newline-safe so multiline values cannot create fake `SERVER_<N>_*` names.
 - The final image runs as non-root `nginx` on port `8080`; keep `/opt/opencode-web/public` read-only and generated config/writable state under `/etc/nginx/conf.d`, `/opt/opencode-web/runtime-configs`, or `/var/cache/nginx`.
 - Root TypeScript uses `erasableSyntaxOnly`; avoid enums, namespaces, parameter properties, or other TS syntax that needs transpilation in wrapper `.ts` files.
-- Bun version sources are duplicated: `package.json` `packageManager` drives GitHub `setup-bun`, while `Dockerfile` and `@types/bun` must be reviewed separately when changing Bun.
+- Bun version sources are duplicated: `package.json` pins `packageManager` and `@types/bun`, `Dockerfile` pins `oven/bun`, and workflows call `oven-sh/setup-bun` without an explicit version.