@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/bin/apifuse-migrate-deployment.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env bun
+
+/**
+ * `apifuse migrate-deployment [path] [--check] [--json] [--drop-codeowners-lock]`
+ *
+ * Retires a provider repository's standalone `deploy.ts`. Deployment intent
+ * has one home — the `deployment` key on `defineProvider({...})` — and only
+ * the fields that differ from the runtime profile are written there. The
+ * command:
+ *
+ * 1. reads `deploy.ts`, subtracts the profile defaults, and proves the
+ *    resulting key resolves to exactly what the file declared;
+ * 2. writes the key into the declaration literal (after `runtime`), removes
+ *    a `deployment` extra from a `{ ...provider, deployment }` default export
+ *    and any `import ... from "./deploy"`;
+ * 3. deletes `deploy.ts` — after checking that no other repository source
+ *    (tests included) imports the module. The `.github/CODEOWNERS`
+ *    `/deploy.ts` lock stays unless `--drop-codeowners-lock` is passed: the
+ *    platform still honors a re-added legacy file until its fallback is
+ *    retired.
+ *
+ * Exit codes: 0 migrated or already migrated; 1 refused (the transform does
+ * not guess — a refusal names the manual step) or missing index.ts.
+ * `--check` reports without writing.
+ */
+
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+import type * as MigrateModule from "../src/cli/migrate-deployment-intent.js";
+
+/** Directories never scanned for deploy-module consumers. */
+const SKIPPED_DIRECTORIES = new Set([
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	"coverage",
+	".turbo",
+	"__generated__",
+]);
+const SOURCE_FILE = /\.(?:[cm]?[jt]s|[jt]sx)$/u;
+
+export const LEGACY_DEPLOY_FILE = "deploy.ts";
+export const CODEOWNERS_FILE = ".github/CODEOWNERS";
+
+export async function main(): Promise<void> {
+	// The transform needs the TypeScript compiler; load it here so a missing
+	// devDependency is a one-line report instead of an import stack trace.
+	let migrateDeploymentIntent: typeof MigrateModule.migrateDeploymentIntent;
+	let findDeployModuleConsumers: typeof MigrateModule.findDeployModuleConsumers;
+	try {
+		({ migrateDeploymentIntent, findDeployModuleConsumers } = await import(
+			"../src/cli/migrate-deployment-intent.js"
+		));
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+	const args = normalizeArgs(process.argv.slice(2));
+	const check = args.includes("--check");
+	const json = args.includes("--json");
+	const dropCodeownersLock = args.includes("--drop-codeowners-lock");
+	const positional = args.filter((argument) => !argument.startsWith("--"));
+	const providerRoot = resolve(positional[0] ?? ".");
+	const indexPath = resolve(providerRoot, "index.ts");
+	const deployPath = resolve(providerRoot, LEGACY_DEPLOY_FILE);
+	const codeownersPath = resolve(providerRoot, CODEOWNERS_FILE);
+
+	const report = (payload: Record<string, unknown>, humanText: string): void => {
+		if (json) {
+			console.log(JSON.stringify({ schemaVersion: 1, providerRoot, ...payload }));
+		} else {
+			console.log(humanText);
+		}
+	};
+
+	if (!existsSync(indexPath)) {
+		report(
+			{ status: "refused", reason: "index.ts not found" },
+			`migrate-deployment: ${indexPath} not found.`,
+		);
+		process.exit(1);
+	}
+
+	const deploySource = existsSync(deployPath) ? readFileSync(deployPath, "utf8") : undefined;
+	const codeownersSource = existsSync(codeownersPath)
+		? readFileSync(codeownersPath, "utf8")
+		: undefined;
+	const result = migrateDeploymentIntent({
+		indexSource: readFileSync(indexPath, "utf8"),
+		deploySource,
+		codeownersSource,
+		dropCodeownersLock,
+		indexFileName: indexPath,
+	});
+
+	if (result.status === "refused") {
+		report(
+			{ status: "refused", reason: result.reason },
+			`migrate-deployment: refused — ${result.reason}\nThis provider needs a manual migration; do not delete deploy.ts without one.`,
+		);
+		process.exit(1);
+	}
+
+	if (result.status === "unchanged") {
+		report(
+			{ status: "unchanged", notes: result.notes },
+			`migrate-deployment: already migrated; nothing to do.${formatNotes(result.notes)}`,
+		);
+		return;
+	}
+
+	if (result.removeDeployFile) {
+		// index.ts is accounted for by the transform; any other source that
+		// imports the module (a test, a helper) would break when it is deleted.
+		const consumers = findDeployModuleConsumers(
+			providerRoot,
+			collectOtherSources(providerRoot, [indexPath, deployPath]),
+		);
+		if (consumers.length > 0) {
+			const reason = `deploy.ts is still imported by ${consumers.join(", ")}; remove or rewrite those imports before migrating.`;
+			report(
+				{ status: "refused", reason },
+				`migrate-deployment: refused — ${reason}\nThis provider needs a manual migration; do not delete deploy.ts without one.`,
+			);
+			process.exit(1);
+		}
+	}
+
+	const touchedPaths: string[] = [];
+	if (result.indexChanged) touchedPaths.push("index.ts");
+	if (result.removeDeployFile) touchedPaths.push(LEGACY_DEPLOY_FILE);
+	if (result.codeownersChanged) touchedPaths.push(CODEOWNERS_FILE);
+	const payload = {
+		shape: result.shape,
+		legacy: result.legacy,
+		intent: result.intent,
+		resolved: result.resolved,
+		resolvedEqual: result.legacy === undefined ? undefined : true,
+		touchedPaths,
+		notes: result.notes,
+	};
+	const intentSummary =
+		Object.keys(result.intent).length === 0
+			? "profile defaults (no deployment key)"
+			: `deployment: ${JSON.stringify(result.intent)}`;
+
+	if (check) {
+		report(
+			{ status: "would-migrate", ...payload },
+			`migrate-deployment: would migrate (${intentSummary}; touches ${touchedPaths.join(", ")}). Run without --check to write.${formatNotes(result.notes)}`,
+		);
+		return;
+	}
+
+	if (result.indexChanged) writeFileSync(indexPath, result.indexSource, "utf8");
+	if (result.codeownersChanged && result.codeownersSource !== undefined) {
+		writeFileSync(codeownersPath, result.codeownersSource, "utf8");
+	}
+	if (result.removeDeployFile) rmSync(deployPath, { force: true });
+	report(
+		{ status: "migrated", ...payload },
+		`migrate-deployment: migrated (${intentSummary}; touched ${touchedPaths.join(", ")}). Review the diff, then run \`apifuse check\` and \`bun run type-check\`.${formatNotes(result.notes)}`,
+	);
+}
+
+function normalizeArgs(argv: string[]): string[] {
+	return argv[0] === "migrate-deployment" ? argv.slice(1) : argv;
+}
+
+/** Every source file under `providerRoot` except `excluded`, with text. */
+function collectOtherSources(
+	providerRoot: string,
+	excluded: readonly string[],
+): { readonly path: string; readonly text: string }[] {
+	const skip = new Set(excluded.map((file) => resolve(file)));
+	const files: { readonly path: string; readonly text: string }[] = [];
+	const walk = (directory: string): void => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			const absolute = join(directory, entry.name);
+			if (entry.isDirectory()) {
+				if (!SKIPPED_DIRECTORIES.has(entry.name)) walk(absolute);
+				continue;
+			}
+			if (!entry.isFile() || !SOURCE_FILE.test(entry.name) || skip.has(resolve(absolute))) continue;
+			files.push({ path: relative(providerRoot, absolute), text: readFileSync(absolute, "utf8") });
+		}
+	};
+	walk(providerRoot);
+	return files;
+}
+
+function formatNotes(notes: readonly string[]): string {
+	return notes.length === 0 ? "" : `\n${notes.map((note) => `  - ${note}`).join("\n")}`;
+}
+
+if (import.meta.main) {
+	await main();
+}

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

@@ -82,11 +82,18 @@ const requiredPaths = [
 	"dist/auth-turn/fixtures/invalid/unknown-top-level-field.json",
 	"src/auth-turn/auth-turn.v1.schema.json",
 ];
+// Test material must never reach the published tarball: it carries no consumer
+// value and the `.deploy.ts.txt` codemod fixtures describe internal provider
+// deployment intent. The `files` negations in package.json do the excluding;
+// these patterns are the ratchet that fails the build when a new test directory
+// escapes them (top-level negations do not cover nested `__tests__`).
+const isPackagedTestMaterial = (path: string): boolean =>
+	path.startsWith("__tests__/") ||
+	path.includes("/__tests__/") ||
+	path.endsWith(".test.ts") ||
+	path.endsWith(".spec.ts");
 const forbiddenMatches = filePaths.filter(
-	(path) =>
-		path.startsWith("src/__tests__/") ||
-		path === "src/index.test.ts" ||
-		path === "bin/apifuse-init.ts",
+	(path) => isPackagedTestMaterial(path) || path === "bin/apifuse-init.ts",
 );
 const missingRequiredPaths = requiredPaths.filter(
 	(path) => !filePaths.includes(path),
@@ -156,9 +163,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.`,
 		);
 	}
 
@@ -168,6 +175,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.");