@apifuse/provider-sdk 2.1.0-beta.1 → 2.1.0-beta.3

package/AUTHORING.md

@@ -74,11 +74,38 @@ External contributors are expected to submit standalone Provider source plus:
 - Health coverage table for every Operation.
 - `bun run check` output.
 - `bun run test` output.
+- `bun run submit-check` score/verdict and generated `submission-report.md`.
 - Fixture evidence and known upstream constraints.
 
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
 deployment projection checks, and release workflows.
 
+### Public local debugging checklist
+
+- Operation smoke requests use the provider server envelope:
+  `{"requestId":"req_local_<operation>","input":{...},"headers":{}}`.
+  Omit `connection` for public/no-auth operations; do not send `connection: null`.
+- Credential-backed smoke requests pass local-only credential material in
+  `connection.secrets`. Keep real values in shell env or `.env`, never in source
+  or fixtures.
+- Auth-flow debugging starts with `/auth/start`, continues with
+  `/auth/continue`, and carries returned `contextPatch` values into the next
+  request's `context`.
+- TLS/browser providers may require local runtime setup outside Provider code:
+  use `bun pm untrusted`/`bun pm trust koffi` for blocked native TLS dependency
+  scripts, `browser.engine: "playwright-stealth"` for TypeScript browser
+  Providers (`nodriver` is Python-runtime only), `bunx playwright install
+  chromium` for local Playwright browser assets, or
+  `CDP_POOL_URL`/`APIFUSE_CDP_POOL_URL` for remote browser debugging.
+
+### Running the pre-submission report
+
+```bash
+bun run submit-check
+```
+
+The report scores review readiness across definition metadata, operation/schema quality, fixtures/tests, health coverage, local smoke evidence, auth safety, secret hygiene, and submission docs. It is not a payout guarantee; any blocker must be fixed before review. For the complete public-only submission checklist, see `SUBMISSION.md` in the SDK package.
+
 ### Running the lint locally
 
 ```bash

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.3
+
+- Add the public `apifuse submit-check` / `apifuse bounty-check` CLI for score-based pre-submission provider quality checks.
+- Ship `SUBMISSION.md` in the npm package so bounty contributors can follow the checklist without access to the private monorepo.
+- Include submit-check in generated provider validation scripts and packed-artifact smoke coverage.
+- Warn, instead of hard-block, generated OAuth starters that have not yet declared persisted credential keys.
+
+## 2.1.0-beta.2
+
+- Harden public bounty contributor DX with server-contract accurate README and generated Provider smoke examples.
+- Add packed-artifact regression checks so stale `connection: null` or missing `requestId` examples cannot ship again.
+- Extend clean-room packed SDK smoke coverage to boot the generated dev server and call `/health` plus `POST /v1/ping`.
+- Document credential, auth-flow, TLS, browser, and Bun trusted-dependency troubleshooting for SDK-only local development.
+
 ## 2.1.0-beta.1
 
 - Fix public `apifuse create` runtime packaging by publishing `@clack/prompts` as a production dependency.

package/README.md

@@ -58,6 +58,7 @@ Removed legacy runtime paths are not supported:
 cd my-provider
 bun run check
 bun run test
+bun run submit-check
 bun run dev
 ```
 
@@ -67,9 +68,73 @@ Smoke the generated local server:
 curl -s http://localhost:3900/health
 curl -s -X POST http://localhost:3900/v1/ping \
   -H 'Content-Type: application/json' \
-  -d '{"input":{"value":"hello"},"headers":{},"connection":null}'
+  -d '{"requestId":"req_local_ping","input":{"value":"hello"},"headers":{}}'
 ```
 
+The operation request body is the same envelope used by the ApiFuse gateway:
+
+| Field | Required | Notes |
+|---|---:|---|
+| `requestId` | yes | Any unique string is fine for local debugging; it is echoed in structured errors. |
+| `input` | yes | The operation input after schema validation. |
+| `headers` | no | Extra caller headers to expose through `ctx.request.headers`. |
+| `connection` | no | Omit for no-auth/public operations. For credential debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+
+Credential-bearing local smoke example:
+
+```bash
+curl -s -X POST http://localhost:3900/v1/me \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "requestId":"req_local_me",
+    "input":{},
+    "connection":{
+      "id":"conn_local_debug",
+      "mode":"credentials",
+      "secrets":{"apiKey":"dev-only-secret"},
+      "scopes":[],
+      "metadata":{},
+      "externalRef":"local-debug"
+    }
+  }'
+```
+
+Auth-flow endpoints use the same `requestId` convention:
+
+```bash
+curl -s -X POST http://localhost:3900/auth/start \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_auth_start","flowId":"flow_local_1","providerId":"my-provider","context":{}}'
+```
+
+If a local smoke returns `{"error":...}`, inspect the JSON error body and the
+`apifuse dev` server log. Validation failures include a `details` array with
+the bad request path; provider/runtime failures include `code`, `message`, and
+`requestId`.
+
+### Local debugging checklist
+
+- **`invalid_request` on `/v1/{operation}`**: confirm the request body includes
+  `requestId` and `input`. Omit `connection` for public/no-auth operations;
+  never send `connection: null`.
+- **Credential-backed operations**: declare `credential.keys`, then pass matching
+  local-only values through `connection.secrets`. Read them in handlers with
+  `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
+- **Provider env secrets**: declare `secrets[]`, set values in your shell or
+  `.env`, and read only those names through `ctx.env.get("NAME")`.
+- **Auth flows**: call `/auth/start`, then `/auth/continue` with the same
+  `flowId`; preserve any returned `contextPatch` in the next local request's
+  `context` object.
+- **TLS-sensitive providers**: if Bun reports blocked lifecycle scripts after
+  install, run `bun pm untrusted`; when it lists trusted SDK native dependencies
+  such as `koffi`, run `bun pm trust koffi` (or `bun pm trust`) before debugging
+  `ctx.tls` failures.
+- **Browser providers**: for TypeScript Providers use `runtime: "browser"` plus
+  `browser.engine: "playwright-stealth"`; `nodriver` is a Python-runtime path.
+  Install local browser assets with `bunx playwright install chromium` when
+  using the Playwright runtime, or set `CDP_POOL_URL`/`APIFUSE_CDP_POOL_URL`
+  when debugging against a remote browser pool.
+
 ## Authoring ergonomics
 
 `defineProvider()` infers each operation handler input from the operation `input` schema. For larger providers, factor operations with `defineOperation()` and compose them later:
@@ -131,9 +196,26 @@ apifuse dev [path]
 apifuse check [path]
 apifuse record [path] --operation <operation> --params '{"value":"hello"}'
 apifuse test [path]
+apifuse submit-check [path] --tier bronze --markdown submission-report.md
+apifuse bounty-check [path]
 apifuse perf <path> --operation <operation>
 ```
 
+`apifuse record` is for real upstream-backed operations that declare
+`upstream.baseUrl` and call the upstream through `ctx.http` or `ctx.tls`. The
+generated local-only `ping` operation intentionally has no upstream and should
+be replaced before recording fixtures.
+
+## Bounty submission readiness
+
+Standalone providers include a pre-submission script:
+
+```bash
+bun run submit-check
+```
+
+This runs the public review-readiness evaluator and writes `submission-report.md`. The report contains provider metadata, a 100-point readiness score, hard blockers, warnings, checklist evidence, and remediation. Blockers override the score; fix them before posting bounty evidence. The command is offline-safe by default and does not execute arbitrary upstream calls. Add local smoke notes to your bounty issue after testing `/health` and `POST /v1/{operation}`. See [`SUBMISSION.md`](./SUBMISSION.md) for the full public-only bounty submission checklist shipped in the npm package.
+
 ## Scope boundary
 
 Generator v1 scaffolds **TypeScript providers only** for this redesign. Python generation remains future work.

package/SUBMISSION.md

@@ -0,0 +1,86 @@
+# Provider bounty submission guide
+
+This guide is for public bounty contributors who only have access to the published `@apifuse/provider-sdk` package. You do **not** need the private ApiFuse monorepo to build or pre-check a Provider.
+
+## Public-only workflow
+
+```bash
+bunx @apifuse/provider-sdk@beta create my-provider --yes
+cd my-provider
+bun run check
+bun run test
+bun run submit-check
+bun run dev
+```
+
+`bun run submit-check` runs `apifuse submit-check . --markdown submission-report.md` in generated Providers.
+
+## What submit-check scores
+
+`apifuse submit-check` produces a 100-point review-readiness score and a verdict:
+
+- `ready` — no blockers or warnings and score is at least 90.
+- `reviewable_with_warnings` — no blockers, but reviewers should inspect the warnings.
+- `blocked` — at least one hard blocker must be fixed before review.
+
+The score is a triage aid, not a payout guarantee. Maintainers still review correctness, upstream behavior, policy fit, and bounty scope.
+
+| Category | Points | Examples |
+|---|---:|---|
+| Definition & metadata | 15 | `defineProvider`, package, Dockerfile, SDK structural checks |
+| Operations & schemas | 15 | strong descriptions, annotations, input/output schemas |
+| Fixtures & tests | 15 | bidirectional fixtures that parse against schemas |
+| Health coverage | 15 | real `healthCheck` or specific `healthCheckUnsupported.reason` |
+| Runtime/local smoke | 10 | `/health` and at least one `POST /v1/{operation}` note |
+| Auth/credential safety | 10 | auth mode and credential declarations are consistent |
+| Security hygiene | 10 | no high-confidence secrets in shareable files |
+| Docs/submission evidence | 10 | README Parameters, Response, Example, submit-check guidance |
+
+## Hard blockers
+
+Fix all blockers before submitting:
+
+- `bun run check` failures.
+- Provider cannot be imported from `index.ts`.
+- Missing handler/input/output for any Operation.
+- Missing fixture request or response.
+- Fixture data does not parse against schemas.
+- Missing `healthCheck` or `healthCheckUnsupported` on any Operation.
+- Credential-backed auth mode without declared credential keys.
+- High-confidence secret or token material in source, README, package metadata, or fixtures.
+
+Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation.
+
+## Safe local smoke evidence
+
+`submit-check` does not call arbitrary live upstream APIs by default. After replacing starter logic, run the Provider locally and record a short evidence note:
+
+```bash
+bun run dev
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/<operation> \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_local_smoke","input":{...},"headers":{}}'
+
+bun run submit-check -- --smoke-note "GET /health and POST /v1/<operation> passed locally with redacted input."
+```
+
+Never paste real credentials, personal data, account numbers, access tokens, cookies, or unredacted upstream responses into issue comments or reports.
+
+## Submission evidence checklist
+
+Include the following when you submit a Provider for review:
+
+- Provider SDK version, for example `bun pm ls @apifuse/provider-sdk` or package.json dependency.
+- Provider id, version, runtime, and auth mode.
+- Operation list with input/output summaries.
+- Health coverage table: one row per Operation with `healthCheck` or `healthCheckUnsupported` and rationale.
+- `bun run check` output.
+- `bun run test` output.
+- `submission-report.md` generated by `bun run submit-check`.
+- Local smoke evidence for `/health` and at least one `POST /v1/{operation}` call.
+- Known upstream constraints: rate limits, paid/destructive calls, auth limits, flaky endpoints, or unsupported probes.
+
+## Maintainer-owned follow-up
+
+After public evidence is submitted, ApiFuse maintainers import accepted standalone Provider work into the private monorepo and run internal registry, generated artifact, deployment projection, and CI checks. Public contributors are not expected to run those private checks.

package/bin/apifuse-check.ts

@@ -7,13 +7,14 @@ import { pathToFileURL } from "node:url";
 import { z } from "zod";
 
 import type { ProviderDefinition } from "../src";
+import { lintProvider } from "../src/lint";
 import { safeParseSchemaSync } from "../src/schema";
 
 const HELP_TEXT = `Usage: apifuse check [path]
 Example: apifuse check providers/airkorea
 Default: apifuse check .`;
 
-type CheckResult = {
+export type CheckResult = {
 	message: string;
 	passed: boolean;
 	details?: string[];
@@ -103,7 +104,7 @@ function resolveFromParents(inputPath: string): string {
 	}
 }
 
-async function runChecks(providerRoot: string): Promise<CheckResult[]> {
+export async function runChecks(providerRoot: string): Promise<CheckResult[]> {
 	const indexPath = resolve(providerRoot, "index.ts");
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
@@ -118,6 +119,7 @@ async function runChecks(providerRoot: string): Promise<CheckResult[]> {
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
+		checkAuthoringLint(provider),
 		checkProviderMetadata(provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
@@ -254,6 +256,32 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 	};
 }
 
+function checkAuthoringLint(
+	provider: ProviderDefinition | undefined,
+): CheckResult {
+	if (!provider) {
+		return {
+			message: "Provider authoring lint has no error-level diagnostics",
+			passed: false,
+		};
+	}
+
+	const diagnostics = lintProvider(provider);
+	const errors = diagnostics.filter(
+		(diagnostic) => diagnostic.level === "error",
+	);
+	const details = diagnostics.map((diagnostic) => {
+		const field = diagnostic.field ? `${diagnostic.field}: ` : "";
+		return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
+	});
+
+	return {
+		message: "Provider authoring lint has no error-level diagnostics",
+		passed: errors.length === 0,
+		details,
+	};
+}
+
 function checkProviderMetadata(
 	provider: ProviderDefinition | undefined,
 ): CheckResult {

package/bin/apifuse-dev.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { existsSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, relative, resolve } from "node:path";
 
 import type { ProviderDefinition } from "../src";
 import {
@@ -51,10 +51,24 @@ export async function main() {
 	console.log(`  POST http://localhost:${port}/auth/poll`);
 	console.log(`  POST http://localhost:${port}/auth/disconnect`);
 
+	const firstOperation = Object.keys(provider.operations)[0];
+	if (firstOperation) {
+		const sampleInput =
+			provider.operations[firstOperation]?.fixtures?.request ?? {};
+		const sampleBody = JSON.stringify({
+			requestId: `req_local_${firstOperation}`,
+			input: sampleInput,
+			headers: {},
+		});
+		console.log("\nSmoke:");
+		console.log(`  curl -s http://localhost:${port}/health`);
+		console.log(
+			`  curl -s -X POST http://localhost:${port}/v1/${firstOperation} -H 'Content-Type: application/json' -d ${shellSingleQuote(sampleBody)}`,
+		);
+	}
+
 	console.log("\nHot reload:");
-	console.log(
-		`  bun --hot ${resolveImportPath("apifuse-dev.ts")} ${args[0] ?? "."}`,
-	);
+	console.log(`  ${renderHotReloadCommand(providerPath, port)}`);
 }
 
 export function createProviderContext(provider: ProviderDefinition): {
@@ -111,8 +125,18 @@ function resolveFromParents(inputPath: string): string {
 	}
 }
 
-function resolveImportPath(fileName: string): string {
-	return resolve(process.cwd(), "bin", fileName);
+function renderHotReloadCommand(providerPath: string, port: number): string {
+	const devEntry = resolve(providerPath, "dev.ts");
+	if (existsSync(devEntry)) {
+		const relativeDevEntry = relative(process.cwd(), devEntry) || "dev.ts";
+		const portPrefix = process.env.PORT ? `PORT=${port} ` : "";
+		return `${portPrefix}bun --hot ${relativeDevEntry}`;
+	}
+	return "rerun `apifuse dev` after edits (no dev.ts entrypoint found)";
+}
+
+function shellSingleQuote(value: string): string {
+	return `'${value.replaceAll("'", "'\\''")}'`;
 }
 
 function createUnsupportedBrowserStub(): BrowserClient {

package/bin/apifuse-pack-check.ts

@@ -33,6 +33,8 @@ const requiredPaths = [
 	"bin/apifuse.ts",
 	"bin/apifuse-create.ts",
 	"bin/apifuse-pack-smoke.ts",
+	"bin/apifuse-submit-check.ts",
+	"SUBMISSION.md",
 	"src/cli/create.ts",
 	"src/cli/templates/provider/index.ts.tpl",
 	"src/cli/templates/provider/README.md.tpl",
@@ -81,7 +83,63 @@ if (packageJson.devDependencies?.["@clack/prompts"]) {
 	);
 }
 
+assertPublicSmokeDocs("README.md", readFileSync("README.md", "utf8"));
+assertPublicSmokeDocs(
+	"src/cli/templates/provider/README.md.tpl",
+	readFileSync("src/cli/templates/provider/README.md.tpl", "utf8"),
+);
+
 console.log(`Packed artifact OK: ${first.filename}`);
 for (const filePath of filePaths) {
 	console.log(`  - ${filePath}`);
 }
+
+function assertPublicSmokeDocs(label: string, content: string): void {
+	if (!content.includes('"requestId":"req_local_ping"')) {
+		throw new Error(
+			`${label} must document the current provider server request envelope with requestId.`,
+		);
+	}
+
+	if (content.includes('"connection":null')) {
+		throw new Error(
+			`${label} must not tell public users to send connection:null; omit connection for no-auth operations.`,
+		);
+	}
+
+	if (!content.includes("bunx playwright install chromium")) {
+		throw new Error(
+			`${label} must include browser runtime troubleshooting for public SDK-only debugging.`,
+		);
+	}
+
+	if (!content.includes("bun pm untrusted")) {
+		throw new Error(
+			`${label} must include Bun trusted-dependency troubleshooting for TLS/browser bounties.`,
+		);
+	}
+
+	if (!content.includes("submit-check")) {
+		throw new Error(
+			`${label} must document the submit-check pre-submission workflow.`,
+		);
+	}
+
+	if (
+		!content.includes('browser.engine: "playwright-stealth"') ||
+		!content.includes("nodriver")
+	) {
+		throw new Error(
+			`${label} must clarify that TypeScript browser providers use playwright-stealth and nodriver is not the TypeScript happy path.`,
+		);
+	}
+
+	if (
+		label.includes("templates/provider/README.md.tpl") &&
+		!content.includes("bun run record -- --operation <operation>")
+	) {
+		throw new Error(
+			`${label} must document fixture recording through a generated package script, not a shell-global apifuse command.`,
+		);
+	}
+}

package/bin/apifuse-pack-smoke.ts

@@ -1,13 +1,20 @@
 #!/usr/bin/env bun
 
-import { execFileSync, spawnSync } from "node:child_process";
+import {
+	type ChildProcess,
+	execFileSync,
+	spawn,
+	spawnSync,
+} from "node:child_process";
 import {
 	existsSync,
 	mkdirSync,
 	mkdtempSync,
+	readFileSync,
 	rmSync,
 	writeFileSync,
 } from "node:fs";
+import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { z } from "zod";
@@ -17,6 +24,20 @@ const PACK_RESULT_SCHEMA = z.array(
 		filename: z.string(),
 	}),
 );
+const HEALTH_RESPONSE_SCHEMA = z.object({
+	status: z.string(),
+	provider: z.string(),
+	version: z.string().optional(),
+});
+const PING_RESPONSE_SCHEMA = z.object({
+	data: z
+		.object({
+			ok: z.boolean(),
+			message: z.string(),
+		})
+		.optional(),
+	error: z.unknown().optional(),
+});
 
 const KEEP_TEMP = process.env.APIFUSE_PACK_SMOKE_KEEP_TEMP === "1";
 
@@ -72,7 +93,10 @@ try {
 
 	const generatedProviderDir = join(consumerDir, "dx-smoke");
 	run("bun", ["run", "check"], generatedProviderDir);
+	run("bun", ["run", "submit-check"], generatedProviderDir);
 	run("bun", ["run", "test"], generatedProviderDir);
+	assertGeneratedReadme(generatedProviderDir);
+	await smokeGeneratedDevServer(generatedProviderDir);
 
 	console.log(
 		`Provider SDK packed-artifact smoke passed: ${tarballPath} -> ${generatedProviderDir}`,
@@ -120,3 +144,159 @@ function run(command: string, args: string[], cwd: string): void {
 		);
 	}
 }
+
+function assertGeneratedReadme(providerDir: string): void {
+	const readme = readFileSync(join(providerDir, "README.md"), "utf8");
+	if (!readme.includes('"requestId":"req_local_ping"')) {
+		throw new Error(
+			"Generated README is missing requestId in local smoke docs.",
+		);
+	}
+	if (readme.includes('"connection":null')) {
+		throw new Error(
+			"Generated README must not document connection:null for no-auth local smoke.",
+		);
+	}
+	if (!readme.includes("bunx playwright install chromium")) {
+		throw new Error(
+			"Generated README is missing browser runtime troubleshooting guidance.",
+		);
+	}
+	if (!readme.includes("bun pm untrusted")) {
+		throw new Error(
+			"Generated README is missing Bun trusted-dependency troubleshooting guidance.",
+		);
+	}
+	if (!readme.includes("bun run submit-check")) {
+		throw new Error(
+			"Generated README must document the submit-check pre-submission workflow.",
+		);
+	}
+	if (!readme.includes("bun run record -- --operation <operation>")) {
+		throw new Error(
+			"Generated README must document fixture recording through the generated record script.",
+		);
+	}
+}
+
+async function smokeGeneratedDevServer(providerDir: string): Promise<void> {
+	const port = await getAvailablePort();
+	const server = spawn("bun", ["run", "dev"], {
+		cwd: providerDir,
+		env: { ...process.env, PORT: String(port) },
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	let output = "";
+	server.stdout?.on("data", (chunk) => {
+		output += chunk.toString();
+	});
+	server.stderr?.on("data", (chunk) => {
+		output += chunk.toString();
+	});
+
+	try {
+		const baseUrl = `http://127.0.0.1:${port}`;
+		await waitForHttp(`${baseUrl}/health`, server, () => output);
+
+		const health = await fetchJson(`${baseUrl}/health`, HEALTH_RESPONSE_SCHEMA);
+		if (health.status !== "ok" || health.provider !== "dx-smoke") {
+			throw new Error(`Unexpected /health payload: ${JSON.stringify(health)}`);
+		}
+
+		const response = await fetch(`${baseUrl}/v1/ping`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				requestId: "req_pack_smoke_ping",
+				input: { value: "hello" },
+				headers: {},
+			}),
+		});
+		const payload = PING_RESPONSE_SCHEMA.parse(await response.json());
+
+		if (!response.ok || payload.data?.ok !== true) {
+			throw new Error(
+				`Unexpected /v1/ping response (${response.status}): ${JSON.stringify(payload)}`,
+			);
+		}
+	} finally {
+		await stopServer(server);
+	}
+}
+
+async function getAvailablePort(): Promise<number> {
+	return await new Promise((resolvePromise, rejectPromise) => {
+		const server = createServer();
+		server.once("error", rejectPromise);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			server.close((error) => {
+				if (error) {
+					rejectPromise(error);
+					return;
+				}
+				if (!address || typeof address === "string") {
+					rejectPromise(new Error("Could not allocate a local TCP port."));
+					return;
+				}
+				resolvePromise(address.port);
+			});
+		});
+	});
+}
+
+async function fetchJson<T>(url: string, schema: z.ZodType<T>): Promise<T> {
+	const response = await fetch(url);
+	if (!response.ok) {
+		throw new Error(`${url} returned ${response.status}`);
+	}
+	return schema.parse(await response.json());
+}
+
+async function waitForHttp(
+	url: string,
+	server: ChildProcess,
+	getOutput: () => string,
+): Promise<void> {
+	const deadline = Date.now() + 10_000;
+	let lastError: unknown;
+
+	while (Date.now() < deadline) {
+		if (server.exitCode !== null) {
+			throw new Error(
+				`Dev server exited early with code ${server.exitCode}\n${getOutput()}`,
+			);
+		}
+
+		try {
+			await fetchJson(url, HEALTH_RESPONSE_SCHEMA);
+			return;
+		} catch (error) {
+			lastError = error;
+			await new Promise((resolve) => setTimeout(resolve, 200));
+		}
+	}
+
+	throw new Error(
+		`Timed out waiting for ${url}: ${lastError instanceof Error ? lastError.message : String(lastError)}\n${getOutput()}`,
+	);
+}
+
+async function stopServer(server: ChildProcess): Promise<void> {
+	if (server.exitCode !== null) {
+		return;
+	}
+	server.kill("SIGTERM");
+	await new Promise<void>((resolvePromise) => {
+		const timeout = setTimeout(() => {
+			if (server.exitCode === null) {
+				server.kill("SIGKILL");
+			}
+			resolvePromise();
+		}, 2_000);
+		server.once("exit", () => {
+			clearTimeout(timeout);
+			resolvePromise();
+		});
+	});
+}