@apifuse/provider-sdk 2.0.0-beta.1 → 2.1.0-beta.1

package/AUTHORING.md

@@ -0,0 +1,93 @@
+## Generator and runtime alignment
+
+- Canonical scaffolding command: `apifuse create`
+- Monorepo contributors should use `apifuse create <name> --preset monorepo`
+- Standalone bounty contributors should use `bunx @apifuse/provider-sdk@beta create <name> --yes` until this release is promoted to `latest`
+- Provider server contract is:
+  - dev default `3900`
+  - start/Docker/container `3000`
+  - `GET /health`
+  - `POST /v1/{operation}`
+  - `POST /auth/start`
+  - `POST /auth/continue`
+  - `POST /auth/poll`
+  - `POST /auth/disconnect`
+- Generator v1 for this redesign scaffolds TypeScript providers only. Python generation is future work.
+
+## Provider Authoring Guide
+
+Provider code is the declaration input to the internal platform registry. The public SDK owns provider authoring/runtime ergonomics; internal docs, deploy, and discovery projections are built downstream from those declarations. `bun run lint:providers` enforces provider authoring standards.
+
+### Description template
+
+Every operation `description` MUST be at least 150 characters and follow this structure:
+
+```
+<What the tool does in one sentence>. Use when <specific scenarios>. Do NOT use for <counter-scenarios; point to alternatives>. Returns <key output fields>. <Important caveats: rate limits, auth, freshness>.
+```
+
+Example:
+```ts
+description:
+  "Retrieves KMA ultra-short-term weather observation for a given grid coordinate in South Korea, " +
+  "including temperature, humidity, wind speed, precipitation, and sky condition. " +
+  "Use when the user asks about current or hourly weather at a specific Korean location. " +
+  "Do NOT use for forecasts beyond 2 days — use kma_mid_forecast instead. " +
+  "Returns hourly data in KST timezone; null values indicate data unavailable. " +
+  "Rate-limited to 1000 calls/day on the free tier.",
+```
+
+### Language policy
+
+- **Structural text**: English (operation `description`, Zod `.describe()`, `whenToUse`, `whenNotToUse`, `derivations`, `inputExamples.scenario/rationale`).
+- **Values only**: native language (fixtures payloads, `inputExamples[].input` values like "대방동", "KRW-BTC", entity catalog entries).
+
+### Required per operation
+
+- `description` — 150+ chars English (error-level rule)
+- Every Zod field in input AND output has `.describe()` including nested objects + array items (error-level rule)
+- `fixtures.request` + `fixtures.response` both present (error-level rule)
+- Exactly one of `healthCheck` or `healthCheckUnsupported` per operation. Prefer `healthCheck` for safe read-only upstream probes; use `healthCheckUnsupported` only with a specific reason for destructive, paid, credential-sensitive, flaky, or otherwise unsafe probes.
+
+### Factored operations
+
+Use `defineOperation()` when an operation is large enough to live beside helper functions or in a separate module. It preserves the same type inference as inline `defineProvider()` operations and can be placed directly in the provider `operations` map. `defineProvider()` accepts Zod and Standard Schema v1-compatible schemas. If config validation fails, the SDK names the field to fix, for example `runtime`, `auth.mode`, `operations.<id>.handler`, or `operations.<id>.fixtures.response`.
+
+### Strongly recommended (warn-level rules)
+
+- `description` includes "use" AND "when" phrasing
+- `inputExamples` with 2+ scenarios for complex input (nested objects, enums, format-sensitive strings)
+- `derivations` for parameters not directly visible in the user query (e.g., `gridX` derived from geocoding)
+
+### Optional but valuable
+
+- `annotations`: `{ readOnly, destructive, idempotent, openWorld, rateLimit }` — agentic safety signals
+- `tags`: operation-level semantic tags for retrieval (e.g., `["weather", "korea", "realtime"]`)
+- `relatedOperations`: `{ alternatives?: string[] }` — links to fallback/sibling operations
+
+### External bounty submission evidence
+
+External contributors are expected to submit standalone Provider source plus:
+
+- SDK version/tag and create command used.
+- Provider id, version, runtime, auth mode, and Operation list.
+- Health coverage table for every Operation.
+- `bun run check` output.
+- `bun run test` output.
+- Fixture evidence and known upstream constraints.
+
+Maintainers own monorepo import under `providers/<id>/`, registry generation,
+deployment projection checks, and release workflows.
+
+### Running the lint locally
+
+```bash
+bun run lint:providers
+```
+
+- Exit 0: all providers pass error-level rules (warnings may still appear)
+- Exit 1: at least one error-level violation; CI will block merge
+
+### CI enforcement
+
+`bun run lint:providers` runs in the `lint-and-typecheck` job on every pull request. Error-level violations block merges.

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @apifuse/provider-sdk Changelog
+
+## 2.1.0-beta.1
+
+- Fix public `apifuse create` runtime packaging by publishing `@clack/prompts` as a production dependency.
+- Update generated Provider starter templates so the sample operation declares a local-only `healthCheckUnsupported` and passes the current health coverage contract.
+- Add packed-artifact smoke coverage for the public create/check/test flow before npm release publishing.
+- Document the public SDK-only bounty contributor path and maintainer-owned monorepo import boundary.
+
+## 2.1.0-beta.0
+
+- BREAKING: collapse the Chrome desktop stealth catalog to `chrome-146` plus the `chrome-desktop` alias. Removed/blocked `chrome-120`, `chrome-124`, `chrome-129`, `chrome-130`, `chrome-131`, `chrome-133`, `chrome-144`, `chrome-146-psk`, `chrome-131-psk`, `chrome-130-psk`, and `edge-131`; migrate callers to `chrome-146`.
+- Make removed Chrome/Edge stealth profile names fail loudly with `SDKError("Unknown stealth profile: <name>")` instead of falling through to a raw TLS identifier.
+
+## 2.0.0-beta.2
+
+- Improve `defineProvider()` operation handler inference from Zod and Standard Schema inputs.
+- Add `defineOperation()` for factored, composable operation declarations.
+- Add descriptive `defineProvider()` validation errors for missing fields, invalid runtime/auth modes, and path-conflicting operation ids.
+- Improve `runStandardTests()` fixture failures with current/expected JSON diffs.
+- Document provider authoring ergonomics and public schema-related types.

package/README.md

@@ -1,44 +1,149 @@
 # @apifuse/provider-sdk
 
-ApiFuse Provider SDK — Build private API automation providers.
+ApiFuse Provider SDK — build provider declarations and runtimes with one public SDK surface and one canonical CLI.
 
-## Installation
+## Install
 
 ```bash
 bun add @apifuse/provider-sdk
 ```
 
-## Quick Start
+For external bounty scaffolding, use the beta tag until this release is promoted
+to `latest`:
 
-```typescript
-import { defineProvider } from '@apifuse/provider-sdk'
-import { z } from 'zod'
+```bash
+bunx @apifuse/provider-sdk@beta create my-provider --yes
+```
 
-export default defineProvider({
-  meta: {
-    id: 'my-api-prices',
-    displayName: 'My API Prices',
-    category: 'finance',
-    version: '1.0.0',
-    runtime: 'standard',
-    upstream: { baseUrl: 'https://api.example.com' },
-  },
-  input: z.object({ id: z.string() }),
-  output: z.object({ price: z.number() }),
-  operations: {
-    prices: {
-      execute: async (ctx, input) => {
-        const res = await ctx.http.get('/prices', { params: { id: input.id } })
-        return res.data as { price: number }
-      },
-    },
+## Create a provider
+
+### Standalone (default)
+
+```bash
+bunx @apifuse/provider-sdk@beta create my-provider --yes
+```
+
+The canonical `create` flow:
+1. scaffolds the provider,
+2. installs dependencies,
+3. runs baseline validation,
+4. prints the exact next local-dev command.
+
+### Monorepo preset
+
+Inside the ApiFuse repository:
+
+```bash
+apifuse create my-provider --preset monorepo
+```
+
+## Provider server contract
+
+- Dev default: `3900`
+- Start/Docker/container contract: `3000`
+- `GET /health`
+- `POST /v1/{operation}`
+- `POST /auth/start`
+- `POST /auth/continue`
+- `POST /auth/poll`
+- `POST /auth/disconnect`
+
+Removed legacy runtime paths are not supported:
+- `/execute/*`
+- `/auth/abort`
+
+## Local workflow
+
+```bash
+cd my-provider
+bun run check
+bun run test
+bun run dev
+```
+
+Smoke the generated local server:
+
+```bash
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/ping \
+  -H 'Content-Type: application/json' \
+  -d '{"input":{"value":"hello"},"headers":{},"connection":null}'
+```
+
+## Authoring ergonomics
+
+`defineProvider()` infers each operation handler input from the operation `input` schema. For larger providers, factor operations with `defineOperation()` and compose them later:
+
+```ts
+import { defineOperation, defineProvider, z } from "@apifuse/provider-sdk/provider"
+
+const search = defineOperation({
+  input: z.object({ q: z.string().describe("Search query") }),
+  output: z.object({ count: z.number().describe("Result count") }),
+  async handler(ctx, input) {
+    return { count: input.q.length }
   },
 })
+
+export default defineProvider({
+  id: "factored-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  meta: { displayName: "Factored", category: "demo" },
+  operations: { search },
+})
 ```
 
-## Testing
+Operation schemas may be Zod schemas or Standard Schema v1-compatible schemas. Invalid configs throw `ProviderError`/`ValidationError` messages that name the offending field, such as `auth.mode` or `operations.search.fixtures.request`.
+
+### Operation health coverage
+
+Every operation must declare exactly one of:
+
+- `healthCheck` — preferred for safe read-only upstream probes.
+- `healthCheckUnsupported` — allowed only when a probe is destructive, paid,
+  credential-sensitive, flaky by design, or otherwise unsafe. The `reason` must
+  be specific.
+
+The generated `ping` operation uses `healthCheckUnsupported` only because it is
+a local scaffold check, not a real upstream API probe.
 
-```typescript
-import { runStandardTests } from '@apifuse/provider-sdk/testing'
-runStandardTests(myProvider)
+### Operation annotations
+
+Operations declare non-functional metadata via `annotations`:
+
+| Field | Type | Notes |
+|---|---|---|
+| `readOnly` | `boolean` | Operation has no side effects (safe to test in production). |
+| `destructive` | `boolean` | Operation modifies/deletes state. |
+| `idempotent` | `boolean` | Safe to retry without duplicate side effects. |
+| `openWorld` | `boolean` | Callable without authentication. |
+| `rateLimit` | `{ calls, window }` | Per-operation rate hint. `window` is `"minute"\|"hour"\|"day"`. |
+| `timeoutMs` | `number` | Per-operation upstream timeout (1–60000 ms). Omit to inherit the gateway global default. |
+
+`defineProvider()` validates `timeoutMs` is an integer in `[1, 60000]` and throws `ValidationError` otherwise. The gateway applies the value via `context.WithTimeout` on every proxied call and clamps defensively to the same bound.
+
+## Canonical CLI surface
+
+```bash
+apifuse create <name>
+apifuse dev [path]
+apifuse check [path]
+apifuse record [path] --operation <operation> --params '{"value":"hello"}'
+apifuse test [path]
+apifuse perf <path> --operation <operation>
 ```
+
+## Scope boundary
+
+Generator v1 scaffolds **TypeScript providers only** for this redesign. Python generation remains future work.
+
+
+## Boundary
+
+Provider cataloging, deployment enrollment, docs indexing, and runtime discovery are internal platform-registry responsibilities and are not part of the public `@apifuse/provider-sdk` contract.
+
+External bounty contributors should submit standalone Provider source plus
+`bun run check` / `bun run test` evidence. ApiFuse maintainers own monorepo
+import, registry generation, deployment projection checks, and release
+publishing.

package/bin/apifuse-check.ts

@@ -7,22 +7,12 @@ import { pathToFileURL } from "node:url";
 import { z } from "zod";
 
 import type { ProviderDefinition } from "../src";
+import { safeParseSchemaSync } from "../src/schema";
 
 const HELP_TEXT = `Usage: apifuse check [path]
-Example: apifuse check providers/upbit-crypto
+Example: apifuse check providers/airkorea
 Default: apifuse check .`;
 
-const manifestSchema = z.object({
-	auth: z.enum(["none", "credentials", "api-key", "oauth2"]),
-	category: z.string().min(1),
-	displayName: z.string().min(1),
-	id: z.string().min(1),
-	language: z.literal("typescript"),
-	runtime: z.enum(["standard", "browser"]),
-	sdkVersion: z.number().int().positive(),
-	version: z.string().min(1),
-});
-
 type CheckResult = {
 	message: string;
 	passed: boolean;
@@ -31,7 +21,7 @@ type CheckResult = {
 
 type SafeParseResult =
 	| { success: true; data: unknown }
-	| { success: false; error: z.ZodError };
+	| { success: false; error: unknown };
 
 export async function main() {
 	const args = normalizeArgs(process.argv.slice(2));
@@ -115,7 +105,6 @@ function resolveFromParents(inputPath: string): string {
 
 async function runChecks(providerRoot: string): Promise<CheckResult[]> {
 	const indexPath = resolve(providerRoot, "index.ts");
-	const manifestPath = resolve(providerRoot, "manifest.json");
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
 
@@ -129,7 +118,7 @@ async function runChecks(providerRoot: string): Promise<CheckResult[]> {
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
-		checkManifest(manifestPath, provider),
+		checkProviderMetadata(provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
 	];
@@ -177,11 +166,11 @@ function checkOperations(
 			failures.push(`${operationId}: missing handler`);
 		}
 
-		if (!hasSafeParse(operation.input)) {
+		if (!hasSchemaParser(operation.input)) {
 			failures.push(`${operationId}: missing input schema`);
 		}
 
-		if (!hasSafeParse(operation.output)) {
+		if (!hasSchemaParser(operation.output)) {
 			failures.push(`${operationId}: missing output schema`);
 		}
 	}
@@ -243,7 +232,7 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 		);
 		if (!requestResult.success) {
 			failures.push(
-				`${operationId}: request fixture invalid (${requestResult.error.issues.map((issue: z.ZodIssue) => issue.message).join(", ")})`,
+				`${operationId}: request fixture invalid (${formatSchemaError(requestResult.error)})`,
 			);
 		}
 
@@ -253,7 +242,7 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 		);
 		if (!responseResult.success) {
 			failures.push(
-				`${operationId}: response fixture invalid (${responseResult.error.issues.map((issue: z.ZodIssue) => issue.message).join(", ")})`,
+				`${operationId}: response fixture invalid (${formatSchemaError(responseResult.error)})`,
 			);
 		}
 	}
@@ -265,58 +254,52 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 	};
 }
 
-function checkManifest(
-	manifestPath: string,
+function checkProviderMetadata(
 	provider: ProviderDefinition | undefined,
 ): CheckResult {
-	if (!existsSync(manifestPath)) {
-		return { message: "manifest.json exists and is valid", passed: false };
-	}
-
-	try {
-		const manifest = manifestSchema.parse(
-			JSON.parse(readFileSync(manifestPath, "utf-8")) as unknown,
-		);
-		const details: string[] = [];
-
-		if (provider) {
-			if (manifest.id !== provider.id) {
-				details.push(
-					`id mismatch: manifest=${manifest.id} provider=${provider.id}`,
-				);
-			}
-
-			if (manifest.displayName !== provider.meta.displayName) {
-				details.push(
-					`displayName mismatch: manifest=${manifest.displayName} provider=${provider.meta.displayName}`,
-				);
-			}
-
-			if (manifest.category !== provider.meta.category) {
-				details.push(
-					`category mismatch: manifest=${manifest.category} provider=${provider.meta.category}`,
-				);
-			}
-
-			if (manifest.runtime !== provider.runtime) {
-				details.push(
-					`runtime mismatch: manifest=${manifest.runtime} provider=${provider.runtime}`,
-				);
-			}
-		}
-
-		return {
-			message: "manifest.json exists and is valid",
-			passed: details.length === 0,
-			details,
-		};
-	} catch (error) {
+	if (!provider) {
 		return {
-			message: "manifest.json exists and is valid",
+			message: "Provider metadata is declared in defineProvider",
 			passed: false,
-			details: [error instanceof Error ? error.message : String(error)],
 		};
 	}
+
+	const details: string[] = [];
+
+	if (!provider.id.trim()) {
+		details.push("provider.id is empty");
+	}
+
+	if (!provider.meta.displayName.trim()) {
+		details.push("provider.meta.displayName is empty");
+	}
+
+	if (!provider.meta.category.trim()) {
+		details.push("provider.meta.category is empty");
+	}
+
+	if (!provider.runtime) {
+		details.push("provider.runtime is missing");
+	}
+
+	if (!provider.auth?.mode) {
+		details.push("provider.auth.mode is missing");
+	}
+
+	return {
+		message: "Provider metadata is declared in defineProvider",
+		passed: details.length === 0,
+		details:
+			details.length > 0
+				? details
+				: [
+						`id: ${provider.id}`,
+						`displayName: ${provider.meta.displayName}`,
+						`category: ${provider.meta.category}`,
+						`runtime: ${provider.runtime}`,
+						`auth: ${provider.auth?.mode ?? "none"}`,
+					],
+	};
 }
 
 function checkDockerfile(dockerfilePath: string): CheckResult {
@@ -388,14 +371,38 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
-function hasSafeParse(value: unknown): value is {
-	safeParse: (input: unknown) => SafeParseResult;
-} {
-	return isRecord(value) && typeof value.safeParse === "function";
+function hasSchemaParser(value: unknown): boolean {
+	return (
+		isRecord(value) &&
+		(typeof value.safeParse === "function" ||
+			(isRecord(value["~standard"]) &&
+				typeof value["~standard"].validate === "function"))
+	);
+}
+
+function formatSchemaError(error: unknown): string {
+	if (error instanceof z.ZodError) {
+		return error.issues.map((issue) => issue.message).join(", ");
+	}
+
+	if (Array.isArray(error)) {
+		return error
+			.map((issue) =>
+				isRecord(issue) && typeof issue.message === "string"
+					? issue.message
+					: String(issue),
+			)
+			.join(", ");
+	}
+
+	return error instanceof Error ? error.message : String(error);
 }
 
-function parseFixture(schema: z.ZodType, fixture: unknown): SafeParseResult {
-	return schema.safeParse(fixture);
+function parseFixture(
+	schema: ProviderDefinition["operations"][string]["input"],
+	fixture: unknown,
+): SafeParseResult {
+	return safeParseSchemaSync(schema, fixture, "fixture");
 }
 
 if (import.meta.main) {

package/bin/apifuse-create.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+
+import { main as runMain } from "../src/cli/create";
+
+export { runMain as main };
+
+if (import.meta.main) {
+	await runMain().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}

package/bin/apifuse-dev.ts

@@ -2,22 +2,21 @@
 
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import * as readline from "node:readline";
 
 import type { ProviderDefinition } from "../src";
 import {
 	createBrowserClient,
+	createCredentialContext,
+	createEnvContext,
 	createHttpClient,
-	createStateContext,
 	createTlsClient,
 	ProviderError,
 } from "../src";
-import type { AuthManager } from "../src/runtime/auth";
 import { createTraceContext } from "../src/runtime/trace";
-import type { ProviderContext, SessionStore } from "../src/types";
+import type { BrowserClient, ProviderContext } from "../src/types";
 
 const HELP_TEXT = `Usage: apifuse dev [path]
-Example: apifuse dev providers/upbit-crypto
+Example: apifuse dev providers/airkorea
 Default: apifuse dev .`;
 
 export async function main() {
@@ -44,23 +43,27 @@ export async function main() {
 	console.log(`  GET  http://localhost:${port}/health`);
 
 	for (const operationId of Object.keys(provider.operations)) {
-		console.log(`  POST http://localhost:${port}/execute/${operationId}`);
-		console.log(`  GET  http://localhost:${port}/schema/${operationId}`);
+		console.log(`  POST http://localhost:${port}/v1/${operationId}`);
 	}
 
+	console.log(`  POST http://localhost:${port}/auth/start`);
+	console.log(`  POST http://localhost:${port}/auth/continue`);
+	console.log(`  POST http://localhost:${port}/auth/poll`);
+	console.log(`  POST http://localhost:${port}/auth/disconnect`);
+
 	console.log("\nHot reload:");
 	console.log(
 		`  bun --hot ${resolveImportPath("apifuse-dev.ts")} ${args[0] ?? "."}`,
 	);
 }
 
-export function createProviderContext(
-	provider: ProviderDefinition,
-	session: SessionStore,
-	authManager: AuthManager,
-): { ctx: ProviderContext } {
+export function createProviderContext(provider: ProviderDefinition): {
+	ctx: ProviderContext;
+} {
 	const ctx: ProviderContext = {
-		auth: authManager.createAuthContext(),
+		env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
+		credential: createCredentialContext(),
+		auth: createUnsupportedAuthStub(),
 		browser:
 			provider.runtime === "browser"
 				? createBrowserClient({
@@ -68,8 +71,6 @@ export function createProviderContext(
 					})
 				: createUnsupportedBrowserStub(),
 		http: createHttpClient(),
-		session,
-		state: createStateContext("dev-secret"),
 		trace: createTraceContext(),
 		tls: createTlsClient("http://localhost"),
 	};
@@ -77,39 +78,6 @@ export function createProviderContext(
 	return { ctx };
 }
 
-export async function runExchangeWithDeferredFieldPrompting(
-	authManager: AuthManager,
-	ctx: ProviderContext,
-	credentials: Record<string, string>,
-	options: { pollIntervalMs?: number } = {},
-): Promise<void> {
-	const promptedFields = new Set<string>();
-	const pollIntervalMs = options.pollIntervalMs ?? 100;
-	let isSettled = false;
-
-	const exchangePromise = authManager.exchange(ctx, credentials).finally(() => {
-		isSettled = true;
-	});
-
-	while (!isSettled) {
-		for (const fieldName of authManager.getPendingFields()) {
-			if (promptedFields.has(fieldName)) {
-				continue;
-			}
-
-			promptedFields.add(fieldName);
-			const value = await promptForField(fieldName);
-			authManager.resolveField(fieldName, value.trim());
-		}
-
-		if (!isSettled) {
-			await Bun.sleep(pollIntervalMs);
-		}
-	}
-
-	await exchangePromise;
-}
-
 function normalizeArgs(argv: string[]): string[] {
 	return argv[0] === "dev" ? argv.slice(1) : argv;
 }
@@ -147,7 +115,7 @@ function resolveImportPath(fileName: string): string {
 	return resolve(process.cwd(), "bin", fileName);
 }
 
-function createUnsupportedBrowserStub(): ProviderContext["browser"] {
+function createUnsupportedBrowserStub(): BrowserClient {
 	return {
 		engine: "playwright-stealth",
 		async newPage() {
@@ -163,20 +131,15 @@ function createUnsupportedBrowserStub(): ProviderContext["browser"] {
 }
 
 async function promptForField(fieldName: string): Promise<string> {
-	const rl = readline.createInterface({
-		input: process.stdin,
-		output: process.stdout,
+	throw new ProviderError(`Auth prompt is unavailable for ${fieldName}`, {
+		code: "AUTH_PROMPT_UNAVAILABLE",
 	});
+}
 
-	try {
-		return await new Promise<string>((resolvePrompt) => {
-			rl.question(`\n[apifuse dev] Enter ${fieldName}: `, (answer) => {
-				resolvePrompt(answer);
-			});
-		});
-	} finally {
-		rl.close();
-	}
+function createUnsupportedAuthStub() {
+	return {
+		requestField: promptForField,
+	};
 }
 
 function assertProviderDefinition(