@apifuse/provider-sdk 2.1.0-beta.0 → 2.1.0-beta.10

package/bin/apifuse-check.ts

@@ -1,24 +1,29 @@
 #!/usr/bin/env bun
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
 
 import type { ProviderDefinition } from "../src";
+import { lintProvider, type ProviderLintMode } from "../src/lint";
 import { safeParseSchemaSync } from "../src/schema";
 
 const HELP_TEXT = `Usage: apifuse check [path]
-Example: apifuse check providers/airkorea
+Example: apifuse check providers/korea-air-quality
 Default: apifuse check .`;
 
-type CheckResult = {
+export type CheckResult = {
 	message: string;
 	passed: boolean;
 	details?: string[];
 };
 
+export type RunChecksOptions = {
+	lintMode?: ProviderLintMode;
+};
+
 type SafeParseResult =
 	| { success: true; data: unknown }
 	| { success: false; error: unknown };
@@ -103,7 +108,10 @@ function resolveFromParents(inputPath: string): string {
 	}
 }
 
-async function runChecks(providerRoot: string): Promise<CheckResult[]> {
+export async function runChecks(
+	providerRoot: string,
+	options: RunChecksOptions = {},
+): Promise<CheckResult[]> {
 	const indexPath = resolve(providerRoot, "index.ts");
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
@@ -112,18 +120,61 @@ async function runChecks(providerRoot: string): Promise<CheckResult[]> {
 		? await import(pathToFileURL(indexPath).href)
 		: undefined;
 	const provider = assertProviderDefinition(providerModule?.default);
+	const providerSourceFiles = collectProviderSourceFiles(providerRoot);
 
 	return [
 		checkIndex(indexPath, provider),
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
+		checkAuthoringLint(provider, providerSourceFiles, options.lintMode),
 		checkProviderMetadata(provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
 	];
 }
 
+function isScannableProviderSourceFile(relativePath: string): boolean {
+	return (
+		/\.(?:ts|tsx|js|jsx|mjs|cjs|sh|bash)$/.test(relativePath) ||
+		/(?:^|\/)Dockerfile(?:\.|$)/.test(relativePath) ||
+		/(?:^|\/)entrypoint(?:\.|$)/.test(relativePath)
+	);
+}
+
+function collectProviderSourceFiles(
+	providerRoot: string,
+): Record<string, string> {
+	const sources: Record<string, string> = {};
+	const skipDirectories = new Set([
+		".git",
+		"node_modules",
+		"dist",
+		"build",
+		".next",
+	]);
+	const visit = (directory: string) => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			const path = resolve(directory, entry.name);
+			if (entry.isDirectory()) {
+				if (!skipDirectories.has(entry.name)) {
+					visit(path);
+				}
+				continue;
+			}
+			if (
+				!entry.isFile() ||
+				!isScannableProviderSourceFile(path.slice(providerRoot.length + 1))
+			) {
+				continue;
+			}
+			sources[path.slice(providerRoot.length + 1)] = readFileSync(path, "utf8");
+		}
+	};
+	visit(providerRoot);
+	return sources;
+}
+
 function checkIndex(
 	indexPath: string,
 	provider: ProviderDefinition | undefined,
@@ -254,6 +305,37 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 	};
 }
 
+function checkAuthoringLint(
+	provider: ProviderDefinition | undefined,
+	providerSourceFiles: Record<string, string>,
+	lintMode: ProviderLintMode = "official",
+): CheckResult {
+	if (!provider) {
+		return {
+			message: "Provider authoring lint has no error-level diagnostics",
+			passed: false,
+		};
+	}
+
+	const diagnostics = lintProvider(
+		{ ...provider, providerSourceFiles },
+		{ mode: lintMode },
+	);
+	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,22 +1,26 @@
 #!/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 {
 	createBrowserClient,
 	createCredentialContext,
 	createEnvContext,
 	createHttpClient,
-	createTlsClient,
+	createProviderCache,
+	createProviderChoiceContext,
+	createStealthClient,
+	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";
 
 const HELP_TEXT = `Usage: apifuse dev [path]
-Example: apifuse dev providers/airkorea
+Example: apifuse dev providers/korea-air-quality
 Default: apifuse dev .`;
 
 export async function main() {
@@ -35,7 +39,7 @@ export async function main() {
 	);
 
 	const { startDevServer } = await import("../src/dev");
-	const port = Number(process.env.PORT) || 3900;
+	const port = Number(process.env.APIFUSE__RUNTIME__PORT) || 3900;
 
 	startDevServer(provider, { port });
 
@@ -51,28 +55,58 @@ 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): {
 	ctx: ProviderContext;
 } {
+	const env = createEnvContext([
+		...(provider.secrets?.map((secret) => secret.name) ?? []),
+		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	]);
+	const credential = createCredentialContext();
+	const state = createMemoryProviderRuntimeState();
 	const ctx: ProviderContext = {
-		env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
-		credential: createCredentialContext(),
+		env,
+		credential,
 		auth: createUnsupportedAuthStub(),
 		browser:
 			provider.runtime === "browser"
 				? createBrowserClient({
+						allowedHosts: provider.allowedHosts,
 						engine: provider.browser?.engine ?? "playwright-stealth",
 					})
 				: createUnsupportedBrowserStub(),
 		http: createHttpClient(),
+		cache: createProviderCache({ providerId: provider.id }),
+		state,
 		trace: createTraceContext(),
-		tls: createTlsClient("http://localhost"),
+		stealth: createStealthClient("http://localhost"),
+		stt: createSttClientFromEnv(provider.stt),
+		choice: createProviderChoiceContext({
+			providerId: provider.id,
+			env,
+			credential,
+			state,
+		}),
 	};
 
 	return { ctx };
@@ -111,13 +145,26 @@ 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.APIFUSE__RUNTIME__PORT
+			? `APIFUSE__RUNTIME__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 {
 	return {
 		engine: "playwright-stealth",
+		async close() {},
 		async newPage() {
 			throw new ProviderError(
 				"Browser runtime is not enabled for this provider",
@@ -127,6 +174,33 @@ function createUnsupportedBrowserStub(): BrowserClient {
 				},
 			);
 		},
+		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',
+				},
+			);
+		},
+		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',
+				},
+			);
+		},
+		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',
+				},
+			);
+		},
 	};
 }
 

package/bin/apifuse-pack-check.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { z } from "zod";
 
 const PACK_RESULT_SCHEMA = z.array(
@@ -28,12 +29,47 @@ if (!first) {
 }
 
 const filePaths = (first.files ?? []).map((file) => file.path);
+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/.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",
+	"src/cli/templates/provider/domain/README.md.tpl",
+	"src/cli/templates/provider/mappers/README.md.tpl",
+	"src/cli/templates/provider/operations/index.ts.tpl",
+	"src/cli/templates/provider/operations/ping.ts.tpl",
+	"src/cli/templates/provider/schemas/ping.ts.tpl",
+	"src/cli/templates/provider/upstream/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",
+];
 const forbiddenMatches = filePaths.filter(
 	(path) =>
 		path.startsWith("src/__tests__/") ||
 		path === "src/index.test.ts" ||
 		path === "bin/apifuse-init.ts",
 );
+const missingRequiredPaths = requiredPaths.filter(
+	(path) => !filePaths.includes(path),
+);
 
 if (forbiddenMatches.length > 0) {
 	throw new Error(
@@ -41,7 +77,91 @@ if (forbiddenMatches.length > 0) {
 	);
 }
 
+if (missingRequiredPaths.length > 0) {
+	throw new Error(
+		`Packed artifact is missing required public SDK files:\n${missingRequiredPaths.join("\n")}`,
+	);
+}
+
+const packageJsonInput: unknown = JSON.parse(
+	readFileSync("package.json", "utf8"),
+);
+const packageJson = z
+	.object({
+		dependencies: z.record(z.string(), z.string()).optional(),
+		devDependencies: z.record(z.string(), z.string()).optional(),
+	})
+	.parse(packageJsonInput);
+
+if (!packageJson.dependencies?.["@clack/prompts"]) {
+	throw new Error(
+		"@clack/prompts is imported by the public create CLI and must be listed in dependencies.",
+	);
+}
+
+if (packageJson.devDependencies?.["@clack/prompts"]) {
+	throw new Error(
+		"@clack/prompts must not be devDependency-only because the published create CLI imports it at runtime.",
+	);
+}
+
+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("impit")) {
+		throw new Error(
+			`${label} must include impit stealth runtime guidance 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.`,
+		);
+	}
+}