@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/bin/apifuse-create.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 
-import { main as runMain } from "../src/cli/create";
+import { main as runMain } from "../src/cli/create.js";
 
 export { runMain as main };
 

package/bin/apifuse-dev.ts

@@ -2,7 +2,7 @@
 
 import { existsSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import type { ProviderDefinition } from "../src";
+import type { ProviderDefinition } from "../src/index.js";
 import {
 	createBrowserClient,
 	createCredentialContext,
@@ -14,10 +14,10 @@ import {
 	createSttClientFromEnv,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 	ProviderError,
-} from "../src";
-import { createMemoryProviderRuntimeState } from "../src/runtime/state";
-import { createTraceContext } from "../src/runtime/trace";
-import type { BrowserClient, ProviderContext } from "../src/types";
+} from "../src/index.js";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
+import { createTraceContext } from "../src/runtime/trace.js";
+import type { BrowserClient, ProviderContext } from "../src/types.js";
 
 const HELP_TEXT = `Usage: apifuse dev [path]
 Example: apifuse dev providers/korea-air-quality
@@ -33,12 +33,9 @@ export async function main() {
 
 	const providerPath = resolveProviderPath(args[0] ?? ".");
 	const providerModule = await import(resolve(providerPath, "index.ts"));
-	const provider = assertProviderDefinition(
-		providerModule.default,
-		providerPath,
-	);
+	const provider = assertProviderDefinition(providerModule.default, providerPath);
 
-	const { startDevServer } = await import("../src/dev");
+	const { startDevServer } = await import("../src/dev.js");
 	const port = Number(process.env.APIFUSE__RUNTIME__PORT) || 3900;
 
 	startDevServer(provider, { port });
@@ -57,8 +54,7 @@ export async function main() {
 
 	const firstOperation = Object.keys(provider.operations)[0];
 	if (firstOperation) {
-		const sampleInput =
-			provider.operations[firstOperation]?.fixtures?.request ?? {};
+		const sampleInput = provider.operations[firstOperation]?.fixtures?.request ?? {};
 		const sampleBody = JSON.stringify({
 			requestId: `req_local_${firstOperation}`,
 			input: sampleInput,
@@ -149,9 +145,7 @@ 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.APIFUSE__RUNTIME__PORT
-			? `APIFUSE__RUNTIME__PORT=${port} `
-			: "";
+		const portPrefix = process.env.APIFUSE__RUNTIME__PORT ? `APIFUSE__RUNTIME__PORT=${port} ` : "";
 		return `${portPrefix}bun --hot ${relativeDevEntry}`;
 	}
 	return "rerun `apifuse dev` after edits (no dev.ts entrypoint found)";
@@ -166,40 +160,28 @@ function createUnsupportedBrowserStub(): BrowserClient {
 		engine: "playwright-stealth",
 		async close() {},
 		async newPage() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser',
+			});
 		},
 		async rawPage() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" and APIFUSE__CDP_POOL__URL to use ctx.browser.rawPage',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" and APIFUSE__CDP_POOL__URL to use ctx.browser.rawPage',
+			});
 		},
 		async withIsolatedContext() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser.withIsolatedContext',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser.withIsolatedContext',
+			});
 		},
 		async solveChallenge() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser.solveChallenge',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser.solveChallenge',
+			});
 		},
 	};
 }
@@ -216,10 +198,7 @@ function createUnsupportedAuthStub() {
 	};
 }
 
-function assertProviderDefinition(
-	value: unknown,
-	providerPath: string,
-): ProviderDefinition {
+function assertProviderDefinition(value: unknown, providerPath: string): ProviderDefinition {
 	if (!isProviderDefinition(value)) {
 		throw new Error(
 			`Expected ${resolve(providerPath, "index.ts")} to export default defineProvider(...)`,
@@ -230,11 +209,7 @@ function assertProviderDefinition(
 }
 
 function isProviderDefinition(value: unknown): value is ProviderDefinition {
-	if (
-		!isRecord(value) ||
-		!isRecord(value.meta) ||
-		!isRecord(value.operations)
-	) {
+	if (!isRecord(value) || !isRecord(value.meta) || !isRecord(value.operations)) {
 		return false;
 	}
 

package/bin/apifuse-pack-check.ts

@@ -36,6 +36,9 @@ const requiredPaths = [
 	"bin/apifuse-submit-check.ts",
 	"SUBMISSION.md",
 	"src/cli/create.ts",
+	"src/cli/templates/provider/.dockerignore.tpl",
+	"src/cli/templates/provider/.gitignore.tpl",
+	"src/cli/templates/provider/Dockerfile.tpl",
 	"src/cli/templates/provider/index.ts.tpl",
 	"src/cli/templates/provider/README.md.tpl",
 	"src/cli/templates/provider/meta.ts.tpl",
@@ -45,6 +48,39 @@ const requiredPaths = [
 	"src/cli/templates/provider/operations/ping.ts.tpl",
 	"src/cli/templates/provider/schemas/ping.ts.tpl",
 	"src/cli/templates/provider/upstream/README.md.tpl",
+	"src/cli/templates/provider/AGENTS.md.tpl",
+	"src/cli/templates/provider/.agents/skills/normalization-standards/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/upstream-contract-verification/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/fixtures-and-recording/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/pagination-and-counts/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/upstream-notes/README.md.tpl",
+	"dist/cli/templates/provider/.dockerignore.tpl",
+	"dist/cli/templates/provider/.gitignore.tpl",
+	"dist/cli/templates/provider/Dockerfile.tpl",
+	"dist/cli/templates/provider/index.ts.tpl",
+	"dist/cli/templates/provider/README.md.tpl",
+	"dist/cli/templates/provider/meta.ts.tpl",
+	"dist/cli/templates/provider/domain/README.md.tpl",
+	"dist/cli/templates/provider/mappers/README.md.tpl",
+	"dist/cli/templates/provider/operations/index.ts.tpl",
+	"dist/cli/templates/provider/operations/ping.ts.tpl",
+	"dist/cli/templates/provider/schemas/ping.ts.tpl",
+	"dist/cli/templates/provider/upstream/README.md.tpl",
+	"dist/cli/templates/provider/AGENTS.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/normalization-standards/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/upstream-contract-verification/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/fixtures-and-recording/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/pagination-and-counts/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/upstream-notes/README.md.tpl",
+	"dist/auth-turn/index.js",
+	"dist/auth-turn/index.d.ts",
+	"dist/auth-turn/auth-turn.v1.schema.json",
+	"dist/auth-turn/fixtures/valid/abort.json",
+	"dist/auth-turn/fixtures/valid/complete.json",
+	"dist/auth-turn/fixtures/invalid/unknown-top-level-field.json",
+	"src/auth-turn/auth-turn.v1.schema.json",
 ];
 const forbiddenMatches = filePaths.filter(
 	(path) =>

package/bin/apifuse-pack-smoke.ts

@@ -1,19 +1,7 @@
 #!/usr/bin/env bun
 
-import {
-	type ChildProcess,
-	execFileSync,
-	spawn,
-	spawnSync,
-} from "node:child_process";
-import {
-	existsSync,
-	mkdirSync,
-	mkdtempSync,
-	readFileSync,
-	rmSync,
-	writeFileSync,
-} from "node:fs";
+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";
@@ -41,9 +29,7 @@ const PING_RESPONSE_SCHEMA = z.object({
 
 const KEEP_TEMP = process.env.APIFUSE__PACK_SMOKE__KEEP_TEMP === "1";
 
-const tempRoot = mkdtempSync(
-	join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"),
-);
+const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"));
 const packDir = join(tempRoot, "pack");
 const consumerDir = join(tempRoot, "consumer");
 const externalWorkspaceDir = join(tempRoot, "external-workspace");
@@ -81,15 +67,7 @@ try {
 
 	run(
 		"bun",
-		[
-			cliBin,
-			"create",
-			"dx-smoke",
-			"--yes",
-			"--json",
-			"--sdk-specifier",
-			tarballSpecifier,
-		],
+		[cliBin, "create", "dx-smoke", "--yes", "--json", "--sdk-specifier", tarballSpecifier],
 		consumerDir,
 	);
 
@@ -99,11 +77,7 @@ try {
 	run("bun", ["run", "test"], generatedProviderDir);
 	assertGeneratedReadme(generatedProviderDir);
 	await smokeGeneratedDevServer(generatedProviderDir);
-	assertExternalWorkspaceTopology(
-		cliBin,
-		externalWorkspaceDir,
-		tarballSpecifier,
-	);
+	assertExternalWorkspaceTopology(cliBin, externalWorkspaceDir, tarballSpecifier);
 
 	console.log(
 		`Provider SDK packed-artifact smoke passed: ${tarballPath} -> ${generatedProviderDir}`,
@@ -148,15 +122,8 @@ function assertExternalWorkspaceTopology(
 		externalWorkspaceDir,
 	);
 
-	const generatedProviderDir = join(
-		externalWorkspaceDir,
-		"external-workspace-smoke",
-	);
-	const forbiddenProviderDir = join(
-		externalWorkspaceDir,
-		"providers",
-		"external-workspace-smoke",
-	);
+	const generatedProviderDir = join(externalWorkspaceDir, "external-workspace-smoke");
+	const forbiddenProviderDir = join(externalWorkspaceDir, "providers", "external-workspace-smoke");
 	if (!existsSync(generatedProviderDir)) {
 		throw new Error(
 			"Public create must generate a one-provider repository at <name>/ even when providers/ exists.",
@@ -168,9 +135,7 @@ function assertExternalWorkspaceTopology(
 		);
 	}
 
-	const packageJson = JSON.parse(
-		readFileSync(join(generatedProviderDir, "package.json"), "utf8"),
-	);
+	const packageJson = JSON.parse(readFileSync(join(generatedProviderDir, "package.json"), "utf8"));
 	const sdkDependency = packageJson?.dependencies?.["@apifuse/provider-sdk"];
 	if (sdkDependency !== tarballSpecifier) {
 		throw new Error(
@@ -178,9 +143,7 @@ function assertExternalWorkspaceTopology(
 		);
 	}
 	if (JSON.stringify(packageJson).includes("workspace:")) {
-		throw new Error(
-			"External bounty workspace scaffold must not contain workspace: dependencies.",
-		);
+		throw new Error("External bounty workspace scaffold must not contain workspace: dependencies.");
 	}
 
 	run("bun", ["install"], generatedProviderDir);
@@ -199,30 +162,20 @@ function assertExternalWorkspaceTopology(
 		},
 	);
 	if (monorepoAttempt.status === 0) {
-		throw new Error(
-			"--preset monorepo must reject outside the private APIFuse monorepo.",
-		);
+		throw new Error("--preset monorepo must reject outside the private APIFuse monorepo.");
 	}
 	const rejectionOutput = `${monorepoAttempt.stdout}\n${monorepoAttempt.stderr}`;
-	if (
-		!rejectionOutput.includes(
-			"Monorepo preset is internal to the APIFuse repository",
-		)
-	) {
+	if (!rejectionOutput.includes("Monorepo preset is internal to the APIFuse repository")) {
 		throw new Error(`Unexpected monorepo rejection output: ${rejectionOutput}`);
 	}
 }
 
 function packSdk(destination: string): { filename: string } {
-	const raw = execFileSync(
-		"npm",
-		["pack", "--json", "--pack-destination", destination],
-		{
-			cwd: process.cwd(),
-			encoding: "utf8",
-			stdio: ["ignore", "pipe", "inherit"],
-		},
-	);
+	const raw = execFileSync("npm", ["pack", "--json", "--pack-destination", destination], {
+		cwd: process.cwd(),
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "inherit"],
+	});
 	const parsed = PACK_RESULT_SCHEMA.parse(JSON.parse(raw));
 	const first = parsed[0];
 	if (!first) {
@@ -252,29 +205,19 @@ 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.",
-		);
+		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.",
-		);
+		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.",
-		);
+		throw new Error("Generated README is missing browser runtime troubleshooting guidance.");
 	}
 	if (!readme.includes("impit")) {
-		throw new Error(
-			"Generated README is missing impit stealth runtime guidance.",
-		);
+		throw new Error("Generated README is missing impit stealth runtime guidance.");
 	}
 	if (!readme.includes("bun run submit-check")) {
-		throw new Error(
-			"Generated README must document the submit-check pre-submission workflow.",
-		);
+		throw new Error("Generated README must document the submit-check pre-submission workflow.");
 	}
 	if (!readme.includes("bun run record -- --operation <operation>")) {
 		throw new Error(
@@ -368,9 +311,7 @@ async function waitForHttp(
 
 	while (Date.now() < deadline) {
 		if (server.exitCode !== null) {
-			throw new Error(
-				`Dev server exited early with code ${server.exitCode}\n${getOutput()}`,
-			);
+			throw new Error(`Dev server exited early with code ${server.exitCode}\n${getOutput()}`);
 		}
 
 		try {

package/bin/apifuse-pack-types.ts

@@ -0,0 +1,266 @@
+#!/usr/bin/env bun
+
+// Guards the published artifact against the nodenext type-resolution regression
+// shipped in 2.2.0-beta.1/beta.2: emitted dist/*.d.ts (and dist/*.js) carried
+// EXTENSIONLESS relative imports, so external provider repos compiling with
+// moduleResolution nodenext could not resolve them. With skipLibCheck the
+// errors were masked and types silently degraded — re-exported ProviderError
+// lost its inherited Error members (name/message) and re-exported zod stopped
+// inferring .refine() callback params (~17 false type errors in
+// apifuse-provider-tabelog, see its PR #16).
+//
+// Three layers, all against the packed tarball (what consumers actually get):
+//   1. @arethetypeswrong/cli — resolution/module-kind audit of every exports
+//      subpath, including internal resolution of relative specifiers in d.ts.
+//   2. A fixture consumer compiled with real tsc under moduleResolution
+//      nodenext and skipLibCheck:false, asserting ProviderError keeps
+//      inherited Error members and zod re-exports keep .refine() inference.
+//   3. A Node (not bun) ESM runtime import — node does not tolerate
+//      extensionless relative specifiers, bun does.
+//
+// A deliberate negative control proves the fixture compiler actually fails on
+// type errors, so this check cannot rot into a false-positive green.
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+
+const PACK_RESULT_SCHEMA = z.array(
+	z.object({
+		filename: z.string(),
+	}),
+);
+
+const KEEP_TEMP = process.env.APIFUSE__PACK_TYPES__KEEP_TEMP === "1";
+const sdkRoot = process.cwd();
+
+const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-types-"));
+const packDir = join(tempRoot, "pack");
+const consumerDir = join(tempRoot, "consumer");
+
+try {
+	mkdirSync(packDir, { recursive: true });
+	mkdirSync(consumerDir, { recursive: true });
+
+	const packed = packSdk(packDir);
+	const tarballPath = resolve(packDir, packed.filename);
+
+	runAreTheTypesWrong(tarballPath);
+	setUpFixtureConsumer(consumerDir, tarballPath);
+	run("bun", ["install"], consumerDir);
+	compileFixtureConsumer(consumerDir);
+	assertNegativeControlFails(consumerDir);
+	runNodeRuntimeImport(consumerDir);
+
+	console.log(`Packed artifact types OK under nodenext: ${tarballPath}`);
+} finally {
+	if (KEEP_TEMP) {
+		console.log(`Keeping pack-types temp directory: ${tempRoot}`);
+	} else {
+		rmSync(tempRoot, { recursive: true, force: true });
+	}
+}
+
+function runAreTheTypesWrong(tarballPath: string): void {
+	// esm-only profile: this package publishes ESM only, so CJS-consumer
+	// resolution failures are expected and out of scope for this guard.
+	run(
+		"bun",
+		[join(sdkRoot, "node_modules", ".bin", "attw"), tarballPath, "--profile", "esm-only"],
+		sdkRoot,
+	);
+}
+
+function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
+	writeFileSync(
+		join(consumerDir, "package.json"),
+		`${JSON.stringify(
+			{
+				private: true,
+				type: "module",
+				dependencies: {
+					"@apifuse/provider-sdk": `file:${tarballPath}`,
+				},
+				devDependencies: {
+					// Pinned to TS 5.x independently of the repo's own TypeScript 7
+					// toolchain: this must reflect what external provider polyrepos
+					// (e.g. apifuse-provider-tabelog) run in their CI.
+					typescript: "^5.9.3",
+					// skipLibCheck:false type-checks transitive deps too (ioredis
+					// references Buffer), so the fixture needs node types like any
+					// real provider repo.
+					"@types/node": "^25.9.3",
+				},
+			},
+			null,
+			2,
+		)}\n`,
+	);
+
+	writeFileSync(
+		join(consumerDir, "tsconfig.json"),
+		`${JSON.stringify(
+			{
+				compilerOptions: {
+					target: "ES2022",
+					module: "nodenext",
+					moduleResolution: "nodenext",
+					strict: true,
+					// skipLibCheck must stay off: it is exactly what masked the
+					// extensionless-d.ts regression downstream.
+					skipLibCheck: false,
+					noEmit: true,
+				},
+				include: ["consumer.ts"],
+			},
+			null,
+			2,
+		)}\n`,
+	);
+
+	writeFileSync(
+		join(consumerDir, "consumer.ts"),
+		[
+			'import { ProviderError, SessionExpiredError, z } from "@apifuse/provider-sdk";',
+			'import { defineCredentialsAuth } from "@apifuse/provider-sdk/provider";',
+			'import { extractProviderContract } from "@apifuse/provider-sdk/contract";',
+			'import { AUTH_TURN_SCHEMA } from "@apifuse/provider-sdk/auth-turn";',
+			'import { serve } from "@apifuse/provider-sdk/server";',
+			'import { runStandardTests } from "@apifuse/provider-sdk/testing";',
+			"",
+			"// ProviderError must keep its inherited Error members under nodenext.",
+			"// When dist d.ts imports fail to resolve, the class type degrades and",
+			"// name/message disappear (the tabelog false-error mode).",
+			'const providerError = new ProviderError("boom");',
+			"const inheritedName: string = providerError.name;",
+			"const inheritedMessage: string = providerError.message;",
+			"const inheritedStack: string | undefined = providerError.stack;",
+			"const isError: Error = providerError;",
+			"const sessionExpired: ProviderError = new SessionExpiredError();",
+			"",
+			"// Re-exported zod must keep .refine() callback parameter inference.",
+			"const refined = z.object({ shopId: z.string() }).refine((value) => value.shopId.length > 0);",
+			'const refinedString = z.string().refine((value) => value.startsWith("tabelog:"));',
+			"",
+			"export const witnesses = {",
+			"	inheritedName,",
+			"	inheritedMessage,",
+			"	inheritedStack,",
+			"	isError,",
+			"	sessionExpired,",
+			"	refined,",
+			"	refinedString,",
+			"	defineCredentialsAuth,",
+			"	extractProviderContract,",
+			"	AUTH_TURN_SCHEMA,",
+			"	serve,",
+			"	runStandardTests,",
+			"};",
+			"",
+		].join("\n"),
+	);
+
+	writeFileSync(
+		join(consumerDir, "negative-control.ts"),
+		[
+			'import { ProviderError } from "@apifuse/provider-sdk";',
+			"",
+			"// Intentionally wrong: name is a string. If this file compiles, the",
+			"// fixture consumer is not actually type-checking and the guard is void.",
+			'export const mustNotCompile: number = new ProviderError("boom").name;',
+			"",
+		].join("\n"),
+	);
+}
+
+function compileFixtureConsumer(consumerDir: string): void {
+	run(
+		"bun",
+		[join(consumerDir, "node_modules", ".bin", "tsc"), "-p", "tsconfig.json"],
+		consumerDir,
+	);
+}
+
+function assertNegativeControlFails(consumerDir: string): void {
+	const result = spawnSync(
+		"bun",
+		[
+			join(consumerDir, "node_modules", ".bin", "tsc"),
+			"--target",
+			"ES2022",
+			"--module",
+			"nodenext",
+			"--moduleResolution",
+			"nodenext",
+			"--strict",
+			"--noEmit",
+			"negative-control.ts",
+		],
+		{ cwd: consumerDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+	);
+	if (result.status === 0) {
+		throw new Error(
+			"Negative control compiled cleanly: the fixture consumer is not detecting type errors, so the nodenext guard proves nothing.",
+		);
+	}
+	if (!`${result.stdout}\n${result.stderr}`.includes("TS2322")) {
+		throw new Error(
+			`Negative control failed for an unexpected reason (wanted TS2322):\n${result.stdout}\n${result.stderr}`,
+		);
+	}
+}
+
+function runNodeRuntimeImport(consumerDir: string): void {
+	// Node, not bun: bun resolves extensionless relative specifiers in
+	// published dist/*.js, node correctly refuses them (ERR_MODULE_NOT_FOUND).
+	run(
+		"node",
+		[
+			"--input-type=module",
+			"-e",
+			[
+				'const sdk = await import("@apifuse/provider-sdk");',
+				'const error = new sdk.ProviderError("boom");',
+				'if (error.name !== "ProviderError" || error.message !== "boom" || !(error instanceof Error)) {',
+				'	throw new Error("ProviderError runtime shape is wrong: " + JSON.stringify({ name: error.name, message: error.message }));',
+				"}",
+				'console.log("node ESM runtime import OK");',
+			].join("\n"),
+		],
+		consumerDir,
+	);
+}
+
+function packSdk(destination: string): { filename: string } {
+	const raw = execFileSync("npm", ["pack", "--json", "--pack-destination", destination], {
+		cwd: sdkRoot,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "inherit"],
+	});
+	const parsed = PACK_RESULT_SCHEMA.parse(JSON.parse(raw));
+	const first = parsed[0];
+	if (!first) {
+		throw new Error("npm pack --json returned no package metadata.");
+	}
+	return first;
+}
+
+function run(command: string, args: string[], cwd: string): void {
+	const result = spawnSync(command, args, {
+		cwd,
+		env: process.env,
+		stdio: "inherit",
+	});
+
+	if (result.error) {
+		throw result.error;
+	}
+
+	if (result.status !== 0) {
+		throw new Error(
+			`Command failed (${[command, ...args].join(" ")}) in ${cwd} with exit code ${result.status}`,
+		);
+	}
+}