@apifuse/provider-sdk 2.1.0-beta.3 → 2.1.0-beta.4

package/src/choice-token.ts

@@ -0,0 +1,164 @@
+import {
+	createCipheriv,
+	createDecipheriv,
+	createHash,
+	createHmac,
+	randomBytes,
+	timingSafeEqual,
+} from "node:crypto";
+
+export type ProviderChoiceTokenPayload = Record<string, unknown>;
+
+export type ProviderChoiceTokenErrorReason =
+	| "invalid_shape"
+	| "invalid_signature"
+	| "invalid_payload"
+	| "stale";
+
+export class ProviderChoiceTokenError extends Error {
+	readonly reason: ProviderChoiceTokenErrorReason;
+
+	constructor(reason: ProviderChoiceTokenErrorReason, message: string) {
+		super(message);
+		this.name = "ProviderChoiceTokenError";
+		this.reason = reason;
+	}
+}
+
+export interface CreateProviderChoiceTokenOptions<
+	TPayload extends ProviderChoiceTokenPayload,
+> {
+	prefix: string;
+	payload: TPayload;
+	secret: string;
+}
+
+export interface ParseProviderChoiceTokenOptions {
+	token: string;
+	prefix: string;
+	secret: string;
+}
+
+export interface FreshProviderChoiceIssuedAtOptions {
+	ttlMs: number;
+	nowMs?: number;
+	futureToleranceMs?: number;
+}
+
+export function createProviderChoiceToken<
+	TPayload extends ProviderChoiceTokenPayload,
+>(options: CreateProviderChoiceTokenOptions<TPayload>): string {
+	const iv = randomBytes(12);
+	const cipher = createCipheriv(
+		"aes-256-gcm",
+		choiceEncryptionKey(options.secret),
+		iv,
+	);
+	const encryptedPayload = Buffer.concat([
+		cipher.update(JSON.stringify(options.payload), "utf8"),
+		cipher.final(),
+	]).toString("base64url");
+	const authTag = cipher.getAuthTag().toString("base64url");
+	const encodedIv = iv.toString("base64url");
+	const signature = signProviderChoiceTokenBody(
+		`${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}`,
+		options.secret,
+	);
+	return `${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}.${signature}`;
+}
+
+export function parseProviderChoiceToken(
+	options: ParseProviderChoiceTokenOptions,
+): ProviderChoiceTokenPayload {
+	const [
+		actualPrefix,
+		encodedIv,
+		encryptedPayload,
+		authTag,
+		signature,
+		...extra
+	] = options.token.split(".");
+	if (
+		actualPrefix !== options.prefix ||
+		!encodedIv ||
+		!encryptedPayload ||
+		!authTag ||
+		!signature ||
+		extra.length > 0
+	) {
+		throw new ProviderChoiceTokenError(
+			"invalid_shape",
+			"Provider choice token shape is invalid.",
+		);
+	}
+
+	const signedBody = `${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}`;
+	const expectedSignature = signProviderChoiceTokenBody(
+		signedBody,
+		options.secret,
+	);
+	const actualBuffer = Buffer.from(signature);
+	const expectedBuffer = Buffer.from(expectedSignature);
+	if (
+		actualBuffer.length !== expectedBuffer.length ||
+		!timingSafeEqual(actualBuffer, expectedBuffer)
+	) {
+		throw new ProviderChoiceTokenError(
+			"invalid_signature",
+			"Provider choice token signature is invalid.",
+		);
+	}
+
+	try {
+		const decipher = createDecipheriv(
+			"aes-256-gcm",
+			choiceEncryptionKey(options.secret),
+			Buffer.from(encodedIv, "base64url"),
+		);
+		decipher.setAuthTag(Buffer.from(authTag, "base64url"));
+		const decrypted = Buffer.concat([
+			decipher.update(Buffer.from(encryptedPayload, "base64url")),
+			decipher.final(),
+		]).toString("utf8");
+		const parsed = JSON.parse(decrypted);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error("payload is not an object");
+		}
+		return Object.fromEntries(Object.entries(parsed));
+	} catch {
+		throw new ProviderChoiceTokenError(
+			"invalid_payload",
+			"Provider choice token payload is invalid.",
+		);
+	}
+}
+
+export function assertFreshProviderChoiceIssuedAt(
+	issuedAtMs: unknown,
+	options: FreshProviderChoiceIssuedAtOptions,
+): number {
+	const parsed =
+		typeof issuedAtMs === "number" ? issuedAtMs : Number(issuedAtMs);
+	const nowMs = options.nowMs ?? Date.now();
+	const futureToleranceMs = options.futureToleranceMs ?? 30_000;
+	if (
+		!Number.isFinite(parsed) ||
+		parsed <= 0 ||
+		nowMs - parsed > options.ttlMs ||
+		parsed - nowMs > futureToleranceMs
+	) {
+		throw new ProviderChoiceTokenError(
+			"stale",
+			"Provider choice token is stale.",
+		);
+	}
+	return parsed;
+}
+
+function choiceEncryptionKey(secret: string): Buffer {
+	return createHash("sha256").update(secret).digest();
+}
+
+function signProviderChoiceTokenBody(body: string, secret: string): string {
+	return createHmac("sha256", secret).update(body).digest("base64url");
+}

package/src/cli/commands.ts

@@ -24,11 +24,9 @@ export const COMMAND_MANIFEST: Record<
 		name: "create",
 		summary:
 			"Scaffold a provider, install dependencies, run baseline validation, and print the next local-dev command.",
-		usage:
-			"apifuse create <provider-name> [--preset standalone|monorepo] [--json] [--dry-run]",
+		usage: "apifuse create <provider-name> [--json] [--dry-run]",
 		examples: [
 			"apifuse create weather-provider",
-			"apifuse create weather-provider --preset monorepo",
 			"apifuse create --config ./apifuse.create.json --json",
 		],
 		modulePath: "./apifuse-create",

package/src/cli/create.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -101,11 +101,9 @@ const TEMPLATE_DIR = fileURLToPath(
 const HELP_TEXT = `Usage: apifuse create <provider-name> [options]
 Examples:
   apifuse create my-provider
-  apifuse create my-provider --preset monorepo
   apifuse create --config ./apifuse.create.json --json
 
 Options:
-  --preset <standalone|monorepo>
   --config <path>
   --output-dir <path>
   --display-name <name>
@@ -115,7 +113,7 @@ Options:
   --yes
   --dry-run
   --json
-  --sdk-specifier <specifier>   # internal/testing override for standalone dependency resolution
+  --sdk-specifier <specifier>   # internal/testing override for dependency resolution
   --help, -h`;
 
 export async function main() {
@@ -273,14 +271,11 @@ async function resolveCreateOptions(
 	config: CreateConfigFile | undefined,
 	cwd: string,
 ): Promise<CreateResolvedOptions> {
-	const detectedWorkspaceRoot = findWorkspaceRoot(cwd);
-	const detectedPreset: CreatePreset = detectedWorkspaceRoot
-		? "monorepo"
-		: "standalone";
+	const internalWorkspaceRoot = findApifuseInternalWorkspaceRoot(cwd);
 
 	const partial: Partial<CreateResolvedOptions> = {
 		name: parsed.name ?? config?.name,
-		preset: parsed.preset ?? config?.preset ?? detectedPreset,
+		preset: parsed.preset ?? config?.preset ?? "standalone",
 		outputDir: parsed.outputDir ?? config?.outputDir,
 		displayName: parsed.displayName ?? config?.displayName,
 		category: parsed.category ?? config?.category,
@@ -289,15 +284,15 @@ async function resolveCreateOptions(
 		sdkSpecifier:
 			parsed.sdkSpecifier ??
 			config?.sdkSpecifier ??
-			process.env.APIFUSE_SDK_SPECIFIER,
+			process.env.APIFUSE__SDK__SPECIFIER,
 		dryRun: parsed.dryRun,
 		json: parsed.json,
 		yes: parsed.yes,
 	};
 
-	if (partial.preset === "monorepo" && !detectedWorkspaceRoot) {
+	if (partial.preset === "monorepo" && !internalWorkspaceRoot) {
 		throw new Error(
-			"Monorepo preset requires a workspace root with a providers/ directory.",
+			"Monorepo preset is internal to the APIFuse repository. External bounty workspaces are one-provider repositories; use the standalone default create flow.",
 		);
 	}
 
@@ -314,7 +309,7 @@ async function resolveCreateOptions(
 			category: partial.category ?? "other",
 			authMode: partial.authMode ?? "none",
 			runtime: partial.runtime ?? "standard",
-			preset: partial.preset ?? detectedPreset,
+			preset: partial.preset ?? "standalone",
 			outputDir: partial.outputDir,
 			dryRun: partial.dryRun ?? false,
 			json: partial.json ?? false,
@@ -324,10 +319,10 @@ async function resolveCreateOptions(
 	}
 
 	if (!partial.json) {
-		intro("Create a new ApiFuse provider");
+		intro("Create a new APIFuse provider");
 		note(
-			`Preset precedence: explicit flags > config file > workspace detection > standalone default\nDetected workspace preset: ${detectedPreset}`,
-			"Preset resolution",
+			"External bounty workspaces are one-provider repositories. The public create flow defaults to standalone.",
+			"Provider workspace",
 		);
 	}
 
@@ -392,22 +387,7 @@ async function resolveCreateOptions(
 					initialValue: "standard",
 				}),
 			)),
-		preset:
-			partial.preset ??
-			(await promptValue(
-				select({
-					message: "Generation preset",
-					options: PRESET_OPTIONS.map((value) => ({
-						label: value,
-						value,
-						hint:
-							value === "standalone"
-								? "Create a clean-room npm-ready provider package."
-								: "Create the provider inside the current ApiFuse monorepo.",
-					})),
-					initialValue: detectedPreset,
-				}),
-			)),
+		preset: partial.preset ?? "standalone",
 		outputDir: partial.outputDir,
 		dryRun: partial.dryRun ?? false,
 		json: partial.json ?? false,
@@ -429,15 +409,15 @@ export async function buildProviderCreatePlan(
 	options: CreateResolvedOptions,
 	cwd: string,
 ): Promise<ProviderCreatePlan> {
-	const workspaceRoot =
-		options.preset === "monorepo" ? findWorkspaceRoot(cwd) : undefined;
-	if (options.preset === "monorepo" && !workspaceRoot) {
+	const resolvedWorkspaceRoot =
+		options.preset === "monorepo"
+			? findApifuseInternalWorkspaceRoot(cwd)
+			: undefined;
+	if (options.preset === "monorepo" && !resolvedWorkspaceRoot) {
 		throw new Error(
-			"Monorepo preset requires a workspace root with a providers/ directory.",
+			"Monorepo preset is internal to the APIFuse repository. External bounty workspaces are one-provider repositories; use the standalone default create flow.",
 		);
 	}
-	const resolvedWorkspaceRoot =
-		options.preset === "monorepo" ? workspaceRoot : undefined;
 	let providerRoot: string;
 	let installCwd: string;
 
@@ -459,33 +439,87 @@ export async function buildProviderCreatePlan(
 		throw new Error(`Target directory already exists: ${providerRoot}`);
 	}
 
+	if (
+		options.sdkSpecifier?.startsWith("workspace:") &&
+		!resolvedWorkspaceRoot
+	) {
+		throw new Error(
+			"workspace:* is only valid inside the APIFuse monorepo because public Provider SDK scaffolds must install from npm or an explicit tarball/file specifier.",
+		);
+	}
+
 	const sdkSpecifier =
 		options.sdkSpecifier ??
-		(options.preset === "monorepo" ? "workspace:*" : `^${packageJson.version}`);
+		(options.preset === "monorepo" && resolvedWorkspaceRoot
+			? "workspace:*"
+			: `^${packageJson.version}`);
 	const relativeProviderRoot = relative(cwd, providerRoot) || options.name;
 	const nextDevCommand = `cd ${relativeProviderRoot} && bun run dev`;
 	const packageName =
 		options.preset === "monorepo"
 			? `@apifuse/provider-${options.name}`
 			: `apifuse-provider-${options.name}`;
+	const templateValues = {
+		PROVIDER_ID: options.name,
+		DISPLAY_NAME: escapeTemplate(options.displayName),
+		CATEGORY: options.category,
+		RUNTIME: options.runtime,
+		BROWSER_BLOCK:
+			options.runtime === "browser"
+				? ',\n  browser: {\n    engine: "playwright-stealth",\n  }'
+				: "",
+		SECRETS_BLOCK: renderSecretsBlock(options.authMode),
+		CREDENTIAL_BLOCK: renderCredentialBlock(options.authMode),
+		AUTH_BLOCK: renderAuthBlock(options.authMode),
+	};
 
 	const files: ProviderPlanFile[] = [
 		{
 			path: resolve(providerRoot, "index.ts"),
-			content: await renderTemplate("index.ts.tpl", {
+			content: await renderTemplate("index.ts.tpl", templateValues),
+		},
+		{
+			path: resolve(providerRoot, "meta.ts"),
+			content: await renderTemplate("meta.ts.tpl", {
 				PROVIDER_ID: options.name,
 				DISPLAY_NAME: escapeTemplate(options.displayName),
 				CATEGORY: options.category,
-				RUNTIME: options.runtime,
-				BROWSER_BLOCK:
-					options.runtime === "browser"
-						? ',\n  browser: {\n    engine: "playwright-stealth",\n  }'
-						: "",
-				SECRETS_BLOCK: renderSecretsBlock(options.authMode),
-				CREDENTIAL_BLOCK: renderCredentialBlock(options.authMode),
-				AUTH_BLOCK: renderAuthBlock(options.authMode),
 			}),
 		},
+		{
+			path: resolve(providerRoot, "operations", "index.ts"),
+			content: await renderTemplate("operations/index.ts.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "operations", "ping.ts"),
+			content: await renderTemplate("operations/ping.ts.tpl", {
+				DISPLAY_NAME: escapeTemplate(options.displayName),
+			}),
+		},
+		{
+			path: resolve(providerRoot, "schemas", "ping.ts"),
+			content: await renderTemplate("schemas/ping.ts.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "upstream", "README.md"),
+			content: await renderTemplate("upstream/README.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "mappers", "README.md"),
+			content: await renderTemplate("mappers/README.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "domain", "README.md"),
+			content: await renderTemplate("domain/README.md.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, "locales", "en.json"),
+			content: renderStarterLocaleCatalog(options.displayName, "en"),
+		},
+		{
+			path: resolve(providerRoot, "locales", "ko.json"),
+			content: renderStarterLocaleCatalog(options.displayName, "ko"),
+		},
 		{
 			path: resolve(providerRoot, "package.json"),
 			content: renderPackageJson({
@@ -611,6 +645,56 @@ function renderTsconfig(): string {
 	)}\n`;
 }
 
+function renderStarterLocaleCatalog(
+	displayName: string,
+	locale: "en" | "ko",
+): string {
+	const catalog = {
+		meta: {
+			displayName,
+			description:
+				locale === "ko"
+					? `${displayName} APIFuse 커뮤니티 기여용 provider starter입니다.`
+					: `${displayName} provider starter for APIFuse community contributions.`,
+		},
+		operations: {
+			ping: {
+				description:
+					locale === "ko"
+						? "생성된 provider wiring이 APIFuse runtime contract를 통해 작은 샘플 payload를 정상적으로 round-trip하는지 확인합니다. 로컬 개발, baseline check, 첫 bounty scaffold 검증에 사용합니다. production data retrieval이나 upstream-specific workflow에는 사용하지 마세요. 이 starter operation은 생성된 프로젝트가 compile, serve, input/output round-trip을 수행하는지 증명하기 위한 용도입니다."
+						: "Confirms the generated provider wiring is operational by echoing a small sample payload through the APIFuse runtime contract. Use when validating local development, baseline checks, or first-pass bounty scaffolds. Do NOT use for production data retrieval or upstream-specific workflows because this starter operation exists only to prove the generated project compiles, serves, and round-trips input/output correctly.",
+			},
+		},
+		schemaDescriptions: {
+			input: {
+				root:
+					locale === "ko"
+						? "생성된 ping operation의 입력 payload"
+						: "Input payload for the generated ping operation.",
+				value:
+					locale === "ko"
+						? "생성된 provider scaffold wiring 검증에 사용하는 샘플 입력값"
+						: "Sample input value used to verify the generated provider scaffold is wired correctly.",
+			},
+			output: {
+				root:
+					locale === "ko"
+						? "생성된 ping operation이 반환하는 출력 payload"
+						: "Output payload returned by the generated ping operation.",
+				ok:
+					locale === "ko"
+						? "생성된 provider가 샘플 요청을 성공적으로 처리했는지 여부"
+						: "Whether the generated provider handled the sample request successfully.",
+				message:
+					locale === "ko"
+						? "생성된 provider가 샘플 payload를 round-trip했음을 보여주는 사람이 읽을 수 있는 확인 메시지"
+						: "Human-readable confirmation that the generated provider round-tripped the sample payload.",
+			},
+		},
+	};
+	return `${JSON.stringify(catalog, null, 2)}\n`;
+}
+
 function renderAuthBlock(authMode: CreateAuthMode): string {
 	switch (authMode) {
 		case "none":
@@ -719,11 +803,11 @@ export function toDisplayName(name: string): string {
 		.join(" ");
 }
 
-function findWorkspaceRoot(cwd: string): string | undefined {
+function findApifuseInternalWorkspaceRoot(cwd: string): string | undefined {
 	let currentDirectory = cwd;
 
 	while (true) {
-		if (existsSync(resolve(currentDirectory, "providers"))) {
+		if (isApifuseInternalWorkspaceRoot(currentDirectory)) {
 			return currentDirectory;
 		}
 
@@ -736,6 +820,31 @@ function findWorkspaceRoot(cwd: string): string | undefined {
 	}
 }
 
+function isApifuseInternalWorkspaceRoot(workspaceRoot: string): boolean {
+	const providerSdkPackageJsonPath = resolve(
+		workspaceRoot,
+		"packages",
+		"provider-sdk",
+		"package.json",
+	);
+	if (!existsSync(providerSdkPackageJsonPath)) {
+		return false;
+	}
+	try {
+		const packageJson = JSON.parse(
+			readFileSync(providerSdkPackageJsonPath, "utf8"),
+		);
+		return (
+			typeof packageJson === "object" &&
+			packageJson !== null &&
+			"name" in packageJson &&
+			packageJson.name === "@apifuse/provider-sdk"
+		);
+	} catch {
+		return false;
+	}
+}
+
 async function writePlan(plan: ProviderCreatePlan): Promise<void> {
 	for (const file of plan.files) {
 		await mkdir(dirname(file.path), { recursive: true });

package/src/cli/templates/provider/README.md.tpl

@@ -12,6 +12,23 @@ bun run submit-check
 ```
 
 
+## Module layout
+
+The generated provider uses the recommended split layout:
+
+```text
+index.ts              # composition root: defineProvider() and wiring only
+meta.ts               # provider metadata
+operations/           # APIFuse operation contracts and handlers
+schemas/              # public input/output schemas near operations
+upstream/             # upstream ceremony: clients, auth, request builders
+mappers/              # upstream-to-APIFuse normalization helpers
+domain/               # shared provider-specific business ceremony
+```
+
+Small providers may stay in one file, but larger providers are easier to
+review when `index.ts` remains a short composition root.
+
 ## Pre-submission report
 
 Before posting bounty evidence, run:
@@ -93,18 +110,18 @@ Structured errors return an `error` object with `code`, `message`,
   `connection.secrets`, and read them with `ctx.credential`.
 - Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
   carry returned `contextPatch` values into the next request's `context`.
-- TLS/browser runtime: if Bun blocks native dependency lifecycle scripts, run
-  `bun pm untrusted` and trust SDK dependencies such as `koffi` before debugging
-  `ctx.tls`; for TypeScript browser Providers use
-  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only),
-  then install local Chromium with `bunx playwright install chromium` or set
-  `CDP_POOL_URL`.
+- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
+  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
+  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
+  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
+  (`nodriver` is Python-runtime only), then install local Chromium with
+  `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
 
 ## Next steps
 
 1. Replace the sample `ping` operation with real upstream logic.
 2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
-   `ctx.tls`, record a fixture with:
+   `ctx.stealth`, record a fixture with:
    `bun run record -- --operation <operation> --params '<json-input>'`.
 3. Replace the starter `healthCheckUnsupported` with a real `healthCheck` for read-only upstream operations when safe.
 4. Extend tests and operation metadata until the provider is bounty-ready.

package/src/cli/templates/provider/dev.ts.tpl

@@ -2,4 +2,4 @@ import { startDevServer } from "@apifuse/provider-sdk";
 
 import provider from "./index";
 
-startDevServer(provider, { port: Number(process.env.PORT) || 3900 });
+startDevServer(provider, { port: Number(process.env.APIFUSE__RUNTIME__PORT) || 3900 });

package/src/cli/templates/provider/domain/README.md.tpl

@@ -0,0 +1,3 @@
+# Domain
+
+Put provider-specific business ceremony here when it is shared across operations and too complex to live inside one operation module.

package/src/cli/templates/provider/index.ts.tpl

@@ -1,23 +1,7 @@
-import { defineProvider, z } from "@apifuse/provider-sdk";
+import { defineProvider } from "@apifuse/provider-sdk/provider";
 
-const InputSchema = z
-  .object({
-    value: z
-      .string()
-      .describe("Sample input value used to verify the generated provider scaffold is wired correctly."),
-  })
-  .describe("Input payload for the generated ping operation.");
-
-const OutputSchema = z
-  .object({
-    ok: z
-      .boolean()
-      .describe("Whether the generated provider handled the sample request successfully."),
-    message: z
-      .string()
-      .describe("Human-readable confirmation that the generated provider round-tripped the sample payload."),
-  })
-  .describe("Output payload returned by the generated ping operation.");
+import { providerMeta } from "./meta";
+import { operations } from "./operations";
 
 export default defineProvider({
   id: "{{PROVIDER_ID}}",
@@ -26,32 +10,6 @@ export default defineProvider({
   allowedHosts: ["api.example.com"],
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
-  meta: {
-    displayName: "{{DISPLAY_NAME}}",
-    description: "{{DISPLAY_NAME}} provider starter for ApiFuse community contributions.",
-    category: "{{CATEGORY}}",
-    tags: ["{{PROVIDER_ID}}", "starter", "community"],
-  },
-  operations: {
-    ping: {
-      description:
-        "Confirms the generated provider wiring is operational by echoing a small sample payload through the ApiFuse runtime contract. Use when validating local development, baseline checks, or first-pass bounty scaffolds. Do NOT use for production data retrieval or upstream-specific workflows because this starter operation exists only to prove the generated project compiles, serves, and round-trips input/output correctly. Returns a success flag plus a message containing the supplied value.",
-      input: InputSchema,
-      output: OutputSchema,
-      handler: async (_ctx, input) => {
-        return {
-          ok: true,
-          message: "{{DISPLAY_NAME}} received: " + input.value,
-        };
-      },
-      fixtures: {
-        request: { value: "hello" },
-        response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
-      },
-      healthCheckUnsupported: {
-        reason:
-          "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
-      },
-    },
-  },
+  meta: providerMeta,
+  operations: operations,
 });

package/src/cli/templates/provider/mappers/README.md.tpl

@@ -0,0 +1,3 @@
+# Mappers
+
+Put normalization helpers here when upstream responses need to become public APIFuse operation outputs.

package/src/cli/templates/provider/meta.ts.tpl

@@ -0,0 +1,7 @@
+export const providerMeta = {
+  displayName: "{{PROVIDER_ID}}",
+  displayNameKey: "meta.displayName",
+  descriptionKey: "meta.description",
+  category: "{{CATEGORY}}",
+  tags: ["{{PROVIDER_ID}}", "starter", "community"],
+} as const;

package/src/cli/templates/provider/operations/index.ts.tpl

@@ -0,0 +1,5 @@
+import { pingOperation } from "./ping";
+
+export const operations = {
+  ping: pingOperation,
+};

package/src/cli/templates/provider/operations/ping.ts.tpl

@@ -0,0 +1,23 @@
+import { defineOperation } from "@apifuse/provider-sdk/provider";
+
+import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
+
+export const pingOperation = defineOperation({
+  descriptionKey: "operations.ping.description",
+  input: pingInputSchema,
+  output: pingOutputSchema,
+  handler: async (_ctx, input) => {
+    return {
+      ok: true,
+      message: "{{DISPLAY_NAME}} received: " + input.value,
+    };
+  },
+  fixtures: {
+    request: { value: "hello" },
+    response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
+  },
+  healthCheckUnsupported: {
+    reason:
+      "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
+  },
+});