@apifuse/provider-sdk 2.1.0-beta.2 → 2.1.0-beta.21

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.
+
+## SDK-only workspace workflow
+
+```bash
+bunx @apifuse/provider-sdk@beta create my-provider --yes
+cd my-provider
+bun run check
+bun run test
+bun run submit-check -- --smoke
+bun run dev
+```
+
+`bun run submit-check -- --smoke` runs the generated `apifuse submit-check . --markdown submission-report.md` script with measured smoke enabled.
+
+## 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.
+- SDK-native source blockers: prefixed Provider ids, `vendor/` SDK shims or imports, raw `.describe()` prose instead of `describeKey`, raw global `fetch()` calls, and excessive `as Type` assertions.
+
+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. SDK-native warnings also flag moderate `as Type` assertion counts and credentialed Providers that never reference `ctx.credential`.
+
+## Measured local smoke
+
+`submit-check` does not call live upstream APIs by default. For smoke scoring,
+run measured smoke so the CLI boots the Provider, checks `/health`, and POSTs
+each operation fixture:
+
+```bash
+bun run submit-check -- --smoke
+```
+
+`APIFUSE__PROVIDER__*` env vars enable live upstream calls. Their absence can
+still produce 7/10 smoke credit when every operation routes and returns a
+structured provider error envelope, but zero schema-valid successes are observed.
+Never paste real credentials, personal data, account numbers, access tokens, cookies, or unredacted upstream responses into workspace PR comments, chat, 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 workspace 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. External contributors are not expected to run those private checks.

package/bin/apifuse-check.ts

@@ -1,17 +1,17 @@
 #!/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 } from "../src/lint";
+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 .`;
 
 export type CheckResult = {
@@ -20,6 +20,10 @@ export type CheckResult = {
 	details?: string[];
 };
 
+export type RunChecksOptions = {
+	lintMode?: ProviderLintMode;
+};
+
 type SafeParseResult =
 	| { success: true; data: unknown }
 	| { success: false; error: unknown };
@@ -104,7 +108,10 @@ function resolveFromParents(inputPath: string): string {
 	}
 }
 
-export 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");
@@ -113,19 +120,61 @@ export 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),
+		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,
@@ -258,6 +307,8 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 
 function checkAuthoringLint(
 	provider: ProviderDefinition | undefined,
+	providerSourceFiles: Record<string, string>,
+	lintMode: ProviderLintMode = "official",
 ): CheckResult {
 	if (!provider) {
 		return {
@@ -266,7 +317,10 @@ function checkAuthoringLint(
 		};
 	}
 
-	const diagnostics = lintProvider(provider);
+	const diagnostics = lintProvider(
+		{ ...provider, providerSourceFiles },
+		{ mode: lintMode },
+	);
 	const errors = diagnostics.filter(
 		(diagnostic) => diagnostic.level === "error",
 	);

package/bin/apifuse-dev.ts

@@ -2,21 +2,25 @@
 
 import { existsSync } from "node:fs";
 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 });
 
@@ -74,19 +78,35 @@ 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 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 };
@@ -129,7 +149,9 @@ 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} ` : "";
+		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)";
@@ -142,6 +164,7 @@ function shellSingleQuote(value: string): string {
 function createUnsupportedBrowserStub(): BrowserClient {
 	return {
 		engine: "playwright-stealth",
+		async close() {},
 		async newPage() {
 			throw new ProviderError(
 				"Browser runtime is not enabled for this provider",
@@ -151,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

@@ -33,9 +33,33 @@ 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) =>
@@ -111,9 +135,15 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
-	if (!content.includes("bun pm untrusted")) {
+	if (!content.includes("impit")) {
 		throw new Error(
-			`${label} must include Bun trusted-dependency troubleshooting for TLS/browser bounties.`,
+			`${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.`,
 		);
 	}
 

package/bin/apifuse-pack-smoke.ts

@@ -39,17 +39,19 @@ const PING_RESPONSE_SCHEMA = z.object({
 	error: z.unknown().optional(),
 });
 
-const KEEP_TEMP = process.env.APIFUSE_PACK_SMOKE_KEEP_TEMP === "1";
+const KEEP_TEMP = process.env.APIFUSE__PACK_SMOKE__KEEP_TEMP === "1";
 
 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");
 
 try {
 	mkdirSync(packDir, { recursive: true });
 	mkdirSync(consumerDir, { recursive: true });
+	mkdirSync(join(externalWorkspaceDir, "providers"), { recursive: true });
 
 	const packed = packSdk(packDir);
 	const tarballPath = resolve(packDir, packed.filename);
@@ -93,9 +95,15 @@ 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);
+	assertExternalWorkspaceTopology(
+		cliBin,
+		externalWorkspaceDir,
+		tarballSpecifier,
+	);
 
 	console.log(
 		`Provider SDK packed-artifact smoke passed: ${tarballPath} -> ${generatedProviderDir}`,
@@ -108,6 +116,103 @@ try {
 	}
 }
 
+function assertExternalWorkspaceTopology(
+	cliBin: string,
+	externalWorkspaceDir: string,
+	tarballSpecifier: string,
+): void {
+	writeFileSync(
+		join(externalWorkspaceDir, "package.json"),
+		`${JSON.stringify(
+			{
+				private: true,
+				type: "module",
+				workspaces: ["providers/*"],
+			},
+			null,
+			2,
+		)}\n`,
+	);
+
+	run(
+		"bun",
+		[
+			cliBin,
+			"create",
+			"external-workspace-smoke",
+			"--yes",
+			"--json",
+			"--sdk-specifier",
+			tarballSpecifier,
+		],
+		externalWorkspaceDir,
+	);
+
+	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.",
+		);
+	}
+	if (existsSync(forbiddenProviderDir)) {
+		throw new Error(
+			"Public create must not generate providers/<name>/ in external bounty workspaces.",
+		);
+	}
+
+	const packageJson = JSON.parse(
+		readFileSync(join(generatedProviderDir, "package.json"), "utf8"),
+	);
+	const sdkDependency = packageJson?.dependencies?.["@apifuse/provider-sdk"];
+	if (sdkDependency !== tarballSpecifier) {
+		throw new Error(
+			`Expected generated provider to depend on packed SDK ${tarballSpecifier}, got ${sdkDependency}`,
+		);
+	}
+	if (JSON.stringify(packageJson).includes("workspace:")) {
+		throw new Error(
+			"External bounty workspace scaffold must not contain workspace: dependencies.",
+		);
+	}
+
+	run("bun", ["install"], generatedProviderDir);
+	run("bun", ["run", "check"], generatedProviderDir);
+	run("bun", ["run", "submit-check"], generatedProviderDir);
+	run("bun", ["run", "test"], generatedProviderDir);
+
+	const monorepoAttempt = spawnSync(
+		"bun",
+		[cliBin, "create", "bad-monorepo-smoke", "--preset", "monorepo", "--yes"],
+		{
+			cwd: externalWorkspaceDir,
+			env: { ...process.env, APIFUSE__SDK__SPECIFIER: tarballSpecifier },
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "pipe"],
+		},
+	);
+	if (monorepoAttempt.status === 0) {
+		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",
+		)
+	) {
+		throw new Error(`Unexpected monorepo rejection output: ${rejectionOutput}`);
+	}
+}
+
 function packSdk(destination: string): { filename: string } {
 	const raw = execFileSync(
 		"npm",
@@ -161,9 +266,14 @@ function assertGeneratedReadme(providerDir: string): void {
 			"Generated README is missing browser runtime troubleshooting guidance.",
 		);
 	}
-	if (!readme.includes("bun pm untrusted")) {
+	if (!readme.includes("impit")) {
 		throw new Error(
-			"Generated README is missing Bun trusted-dependency troubleshooting guidance.",
+			"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.",
 		);
 	}
 	if (!readme.includes("bun run record -- --operation <operation>")) {
@@ -177,7 +287,8 @@ 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) },
+		env: { ...process.env, APIFUSE__RUNTIME__PORT: String(port) },
+		detached: process.platform !== "win32",
 		stdio: ["ignore", "pipe", "pipe"],
 	});
 	let output = "";
@@ -280,11 +391,11 @@ async function stopServer(server: ChildProcess): Promise<void> {
 	if (server.exitCode !== null) {
 		return;
 	}
-	server.kill("SIGTERM");
+	killProcessTree(server, "SIGTERM");
 	await new Promise<void>((resolvePromise) => {
 		const timeout = setTimeout(() => {
 			if (server.exitCode === null) {
-				server.kill("SIGKILL");
+				killProcessTree(server, "SIGKILL");
 			}
 			resolvePromise();
 		}, 2_000);
@@ -294,3 +405,19 @@ async function stopServer(server: ChildProcess): Promise<void> {
 		});
 	});
 }
+
+function killProcessTree(server: ChildProcess, signal: NodeJS.Signals): void {
+	if (server.pid === undefined) {
+		return;
+	}
+
+	try {
+		if (process.platform === "win32") {
+			server.kill(signal);
+			return;
+		}
+		process.kill(-server.pid, signal);
+	} catch {
+		server.kill(signal);
+	}
+}