@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.51

package/bin/apifuse-dev.ts

@@ -2,21 +2,30 @@
 
 import { existsSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import type { ProviderDefinition } from "../src/index.js";
 import {
-	createBrowserClient,
 	createCredentialContext,
 	createEnvContext,
 	createHttpClient,
+	createInProcessProviderEngine,
+	createOcrClientFromEnv,
 	createProviderCache,
 	createProviderChoiceContext,
-	createStealthClient,
+	createProviderEnvironment,
+	createUnsupportedResolverClient,
 	createSttClientFromEnv,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	readEngineProxyCredentials,
+	type ProviderDefinition,
+	type ProviderEngineBindingCandidates,
 	ProviderError,
+	type ProviderProxyPolicy,
 } from "../src/index.js";
+import { createBrowserClient } from "../src/runtime/browser.js";
+import { createResolverClientFromEnv } from "../src/runtime/resolver.js";
 import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
+import { createStealthClient } from "../src/runtime/stealth.js";
 import { createTraceContext } from "../src/runtime/trace.js";
+import { getStealthProfile } from "../src/stealth/profiles.js";
 import type { BrowserClient, ProviderContext } from "../src/types.js";
 
 const HELP_TEXT = `Usage: apifuse dev [path]
@@ -74,14 +83,20 @@ export async function main() {
 export function createProviderContext(provider: ProviderDefinition): {
 	ctx: ProviderContext;
 } {
-	const env = createEnvContext([
-		...(provider.secrets?.map((secret) => secret.name) ?? []),
-		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-	]);
+	const providerEnvironment = createProviderEnvironment(
+		process.env,
+		provider.secrets?.map((secret) => secret.name) ?? [],
+	);
+	const providerEnv = { get: (key: string) => providerEnvironment[key] };
+	const engineEnv = createEnvContext([PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV]);
+	const engineCredentials = readEngineProxyCredentials();
 	const credential = createCredentialContext();
 	const state = createMemoryProviderRuntimeState();
-	const ctx: ProviderContext = {
-		env,
+	const cache = createProviderCache({ providerId: provider.id });
+	const proxyPolicy = resolveNativeProxyPolicy(provider);
+	const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+	const candidates: ProviderEngineBindingCandidates = {
+		env: providerEnv,
 		credential,
 		auth: createUnsupportedAuthStub(),
 		browser:
@@ -92,22 +107,51 @@ export function createProviderContext(provider: ProviderDefinition): {
 					})
 				: createUnsupportedBrowserStub(),
 		http: createHttpClient(),
-		cache: createProviderCache({ providerId: provider.id }),
+		cache,
 		state,
 		trace: createTraceContext(),
-		stealth: createStealthClient("http://localhost"),
+		stealth: createStealthClient("http://localhost", {
+			...(provider.stealth ? { stealth: provider.stealth } : {}),
+		}),
+		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
+		resolver: provider.resolver
+			? createResolverClientFromEnv(provider.resolver, engineCredentials, {
+					allowedHosts: provider.allowedHosts,
+					cache,
+					...(proxyPolicy
+						? {
+								proxyIntent: {
+									mode: proxyPolicy.mode,
+									upstream: { proxy: provider.proxy },
+									...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
+								},
+							}
+						: {}),
+				})
+			: createUnsupportedResolverClient("Provider does not declare resolver capability"),
 		choice: createProviderChoiceContext({
 			providerId: provider.id,
-			env,
+			env: engineEnv,
 			credential,
 			state,
 		}),
 	};
+	const ctx = createInProcessProviderEngine().attach({
+		provider,
+		bindings: candidates,
+	}) as ProviderContext;
 
 	return { ctx };
 }
 
+function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPolicy | undefined {
+	if (typeof provider.proxy === "object") return provider.proxy;
+	if (provider.proxy === true) return { mode: "optional" };
+	if (provider.proxy === false) return { mode: "disabled" };
+	return undefined;
+}
+
 function normalizeArgs(argv: string[]): string[] {
 	return argv[0] === "dev" ? argv.slice(1) : argv;
 }
@@ -216,7 +260,7 @@ function isProviderDefinition(value: unknown): value is ProviderDefinition {
 	return (
 		typeof value.id === "string" &&
 		typeof value.version === "string" &&
-		(value.runtime === "standard" || value.runtime === "browser") &&
+		(value.runtime === "standard" || value.runtime === "shared" || value.runtime === "browser") &&
 		typeof value.meta.displayName === "string" &&
 		typeof value.meta.category === "string"
 	);

package/bin/apifuse-migrate-operation-declaration.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+
+/**
+ * `apifuse migrate-operation-declaration [path] [--check] [--json]`
+ *
+ * Rewrites ADR-0009's legacy nested operation declarations to the flat
+ * authoring contract. The run is repository-atomic: any declaration the
+ * codemod cannot prove leaves every source file untouched and exits 2.
+ */
+
+import { resolve } from "node:path";
+
+import { migrateOperationDeclarationRepository } from "../src/cli/migrate-operation-declaration.js";
+
+export async function main(): Promise<number> {
+	const args = process.argv.slice(3);
+	const check = args.includes("--check");
+	const json = args.includes("--json");
+	const positional = args.filter((argument) => !argument.startsWith("--"));
+	const providerRoot = resolve(positional[0] ?? ".");
+	const result = migrateOperationDeclarationRepository(providerRoot, { check });
+
+	if (json) {
+		console.log(
+			JSON.stringify({
+				schemaVersion: 1,
+				command: "migrate-operation-declaration",
+				...result,
+			}),
+		);
+	} else if (result.status === "refused") {
+		console.error(
+			`migrate-operation-declaration: refused ${result.refusals.length} declaration(s); no files were written.`,
+		);
+		for (const item of result.refusals) {
+			console.error(`  ${item.file} [${item.operationKey}] ${item.reason}: ${item.detail}`);
+		}
+	} else if (result.status === "unchanged") {
+		console.log("migrate-operation-declaration: already flat; nothing to do.");
+	} else {
+		const verb = result.status === "would-migrate" ? "would migrate" : "migrated";
+		const sidecar = result.sidecar === undefined ? "" : ` and ${result.sidecar}`;
+		console.log(
+			`migrate-operation-declaration: ${verb} ${result.operationCount} operation(s) across ${result.changedFiles.length} file(s)${sidecar}.`,
+		);
+	}
+
+	const exitCode = result.status === "refused" ? 2 : 0;
+	process.exitCode = exitCode;
+	return exitCode;
+}
+
+if (import.meta.main) {
+	process.exit(await main());
+}

package/bin/apifuse-migrate-shape.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env bun
+
+/**
+ * `apifuse migrate-shape [path] [--check] [--json]`
+ *
+ * Applies the provider authoring-shape migration for the phase-separated SDK
+ * (2.2.0-beta.37+) to a provider repository. Two coordinated transforms:
+ *
+ * 1. `index.ts`: single-phase `defineProvider({...operations})` becomes the
+ *    two-phase declaration builder. The old shape default-exports a builder
+ *    FUNCTION under the new SDK, so the module stops loading.
+ * 2. Every provider source file: legacy `defineOperation(config)` /
+ *    `defineStreamOperation(config)` become the curried
+ *    `defineOperation<ProviderContext>()(config)`. The legacy call returns
+ *    the inner factory with the config swallowed, so every operation in the
+ *    map turns into a function and finalizeProvider rejects the provider
+ *    with a misleading health-check error.
+ *
+ * Both halves belong to the same SDK bump: this transform and the pin bump
+ * must land in one commit.
+ *
+ * Exit codes: 0 migrated or already migrated; 1 any skip (the transform
+ * refuses to guess) or a missing index.ts. `--check` reports without
+ * writing. A skip is a hard stop for fan-out callers — never pair a pin bump
+ * with a skipped migration.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+import { migrateOperationShape } from "../src/cli/migrate-operation-shape.js";
+import { migrateProviderShape } from "../src/cli/migrate-provider-shape.js";
+
+const SOURCE_SKIP_DIRECTORIES = new Set([
+	"node_modules",
+	"__tests__",
+	"__fixtures__",
+	".git",
+	"dist",
+]);
+
+type FileOutcome = {
+	readonly path: string;
+	readonly status: string;
+	readonly detail?: string;
+};
+
+export async function main(): Promise<void> {
+	const args = process.argv.slice(3);
+	const check = args.includes("--check");
+	const json = args.includes("--json");
+	const positional = args.filter((argument) => !argument.startsWith("--"));
+	const providerRoot = resolve(positional[0] ?? ".");
+	const indexPath = resolve(providerRoot, "index.ts");
+
+	const report = (payload: Record<string, unknown>, humanText: string): void => {
+		if (json) {
+			console.log(
+				JSON.stringify({ schemaVersion: 2, providerRoot, ...payload }),
+			);
+		} else {
+			console.log(humanText);
+		}
+	};
+
+	if (!existsSync(indexPath)) {
+		report(
+			{ status: "skipped", reason: "index.ts not found" },
+			`migrate-shape: ${indexPath} not found.`,
+		);
+		process.exit(1);
+	}
+
+	// ── Pass 1: provider two-phase shape on index.ts
+	const indexSource = readFileSync(indexPath, "utf8");
+	const providerResult = migrateProviderShape(indexSource, indexPath);
+
+	if (providerResult.status === "skipped") {
+		report(
+			{ status: "skipped", stage: "provider-shape", reason: providerResult.reason },
+			`migrate-shape: skipped — ${providerResult.reason}\nThis provider needs a manual migration; do not bump its SDK pin without one.`,
+		);
+		process.exit(1);
+	}
+
+	// ── Pass 2: operation currying across the provider's source tree.
+	// The index.ts input for this pass is pass 1's OUTPUT, so a provider
+	// whose index both holds the declaration and defines operations gets
+	// both transforms in one write.
+	const indexAfterProvider = providerResult.code;
+	const outcomes: FileOutcome[] = [];
+	const pendingWrites = new Map<string, string>();
+	let operationRewrites = 0;
+
+	for (const sourcePath of collectSourceFiles(providerRoot)) {
+		const isIndex = sourcePath === indexPath;
+		const input = isIndex
+			? indexAfterProvider
+			: readFileSync(sourcePath, "utf8");
+		// Operation modules import the alias from the provider entry; the
+		// entry file declares it itself.
+		const contextSpecifier = isIndex
+			? "./index"
+			: relativeImportToIndex(sourcePath, providerRoot);
+		const result = migrateOperationShape(input, sourcePath, contextSpecifier);
+
+		if (result.status === "skipped") {
+			report(
+				{
+					status: "skipped",
+					stage: "operation-shape",
+					file: relative(providerRoot, sourcePath),
+					reason: result.reason,
+				},
+				`migrate-shape: skipped at ${relative(providerRoot, sourcePath)} — ${result.reason}\nThis provider needs a manual migration; do not bump its SDK pin without one.`,
+			);
+			process.exit(1);
+		}
+		if (result.status === "migrated") {
+			operationRewrites += result.rewrites;
+			pendingWrites.set(sourcePath, result.code);
+			outcomes.push({
+				path: relative(providerRoot, sourcePath),
+				status: "curried",
+				detail: `${result.rewrites} call site(s)`,
+			});
+		} else if (isIndex && providerResult.status === "migrated") {
+			// Provider shape changed even though no operation calls did.
+			pendingWrites.set(sourcePath, result.code);
+		}
+	}
+
+	const providerChanged = providerResult.status === "migrated";
+	const anythingChanged = providerChanged || operationRewrites > 0;
+
+	if (!anythingChanged) {
+		report(
+			{ status: "unchanged" },
+			"migrate-shape: already migrated; nothing to do.",
+		);
+		return;
+	}
+
+	if (check) {
+		report(
+			{
+				status: "would-migrate",
+				providerShape: providerChanged ? providerResult.kind : "unchanged",
+				operationCallSites: operationRewrites,
+				files: outcomes,
+			},
+			`migrate-shape: would migrate (provider: ${providerChanged ? providerResult.kind : "unchanged"}, operation call sites: ${operationRewrites}). Run without --check to write.`,
+		);
+		return;
+	}
+
+	for (const [path, code] of pendingWrites) {
+		writeFileSync(path, code, "utf8");
+	}
+	report(
+		{
+			status: "migrated",
+			providerShape: providerChanged ? providerResult.kind : "unchanged",
+			operationCallSites: operationRewrites,
+			files: outcomes,
+		},
+		`migrate-shape: migrated (provider: ${providerChanged ? providerResult.kind : "unchanged"}, operation call sites: ${operationRewrites} across ${pendingWrites.size} file(s)). Review the diff, then run \`apifuse check\` and \`bun test\`.`,
+	);
+}
+
+/** Provider-authored .ts sources, excluding tests, fixtures, and build output. */
+function collectSourceFiles(root: string): string[] {
+	const files: string[] = [];
+	const walk = (directory: string): void => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			if (entry.isDirectory()) {
+				if (SOURCE_SKIP_DIRECTORIES.has(entry.name)) continue;
+				walk(join(directory, entry.name));
+				continue;
+			}
+			if (!entry.name.endsWith(".ts")) continue;
+			if (entry.name.endsWith(".d.ts")) continue;
+			if (entry.name.endsWith(".test.ts")) continue;
+			files.push(join(directory, entry.name));
+		}
+	};
+	walk(root);
+	return files.sort();
+}
+
+/** `operations/foo.ts` -> `../index`; `operations/a/b.ts` -> `../../index`. */
+function relativeImportToIndex(sourcePath: string, providerRoot: string): string {
+	const fromDirectory = dirname(sourcePath);
+	let specifier = relative(fromDirectory, join(providerRoot, "index"));
+	specifier = specifier.split("\\").join("/");
+	if (!specifier.startsWith(".")) specifier = `./${specifier}`;
+	return specifier;
+}
+
+if (import.meta.main) {
+	await main();
+}

package/bin/apifuse-pack-check.ts

@@ -48,6 +48,13 @@ 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",
@@ -60,6 +67,13 @@ const requiredPaths = [
 	"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",
@@ -142,9 +156,9 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
-	if (!content.includes("impit")) {
+	if (!content.includes("wreq-js")) {
 		throw new Error(
-			`${label} must include impit stealth runtime guidance for TLS/browser bounties.`,
+			`${label} must include wreq-js stealth runtime guidance for TLS/browser bounties.`,
 		);
 	}
 
@@ -154,6 +168,12 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
+	if (!content.includes("Chrome, Firefox, and Safari")) {
+		throw new Error(
+			`${label} must document the browser families supported by the TypeScript stealth runtime.`,
+		);
+	}
+
 	if (
 		!content.includes('browser.engine: "playwright-stealth"') ||
 		!content.includes("nodriver")

package/bin/apifuse-pack-smoke.ts

@@ -59,6 +59,21 @@ try {
 	);
 
 	run("bun", ["install"], consumerDir);
+	run(
+		"bun",
+		[
+			"--eval",
+			[
+				'import { resolveProxy } from "@apifuse/provider-sdk";',
+				'if (typeof resolveProxy !== "function") throw new Error("resolveProxy is not exported");',
+				'const resolved = await resolveProxy({ proxy: "http://127.0.0.1:8080" });',
+				'if (resolved.url !== "http://127.0.0.1:8080") throw new Error("resolveProxy returned the wrong URL");',
+				'console.log("packed root resolveProxy export OK");',
+			].join("\n"),
+		],
+		consumerDir,
+	);
+	smokePackedStealthNative(consumerDir);
 
 	const cliBin = join(consumerDir, "node_modules", ".bin", "apifuse");
 	if (!existsSync(cliBin)) {
@@ -202,6 +217,43 @@ function run(command: string, args: string[], cwd: string): void {
 	}
 }
 
+function smokePackedStealthNative(consumerDir: string): void {
+	run(
+		"bun",
+		[
+			"--eval",
+			[
+				'import { createServer } from "node:http";',
+				'import { createStealthClient } from "@apifuse/provider-sdk/runtime/stealth";',
+				"const server = createServer((_request, response) => {",
+				'  response.setHeader("set-cookie", "pack_native_cookie=landed; Path=/");',
+				'  response.end("packed native stealth ok");',
+				"});",
+				"await new Promise((resolve, reject) => {",
+				'  server.once("error", reject);',
+				'  server.listen(0, "127.0.0.1", resolve);',
+				"});",
+				"const address = server.address();",
+				'if (!address || typeof address === "string") throw new Error("Local server has no TCP address");',
+				'const baseUrl = "http://127.0.0.1:" + address.port;',
+				'const session = createStealthClient(baseUrl).createSession({ stealth: { browser: "safari", os: "macos" } });',
+				"try {",
+				'  const response = await session.fetch("/native");',
+				'  if (response.body !== "packed native stealth ok") throw new Error("Unexpected stealth body: " + response.body);',
+				'  if (session.cookies.get("pack_native_cookie", baseUrl + "/native") !== "landed") {',
+				'    throw new Error("Packed stealth Set-Cookie did not land in the SDK jar");',
+				"  }",
+				'  console.log("packed native Safari stealth request OK");',
+				"} finally {",
+				"  session.close();",
+				"  await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));",
+				"}",
+			].join("\n"),
+		],
+		consumerDir,
+	);
+}
+
 function assertGeneratedReadme(providerDir: string): void {
 	const readme = readFileSync(join(providerDir, "README.md"), "utf8");
 	if (!readme.includes('"requestId":"req_local_ping"')) {
@@ -213,8 +265,11 @@ function assertGeneratedReadme(providerDir: string): void {
 	if (!readme.includes("bunx playwright install chromium")) {
 		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.");
+	if (!readme.includes("wreq-js")) {
+		throw new Error("Generated README is missing wreq-js stealth runtime guidance.");
+	}
+	if (!readme.includes("Chrome, Firefox, and Safari")) {
+		throw new Error("Generated README is missing supported stealth browser families.");
 	}
 	if (!readme.includes("bun run submit-check")) {
 		throw new Error("Generated README must document the submit-check pre-submission workflow.");