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

package/AUTHORING.md

@@ -2,7 +2,7 @@
 
 - Canonical scaffolding command: `apifuse create`
 - Monorepo contributors should use `apifuse create <name> --preset monorepo`
-- Standalone users should use `bunx @apifuse/provider-sdk create <name>`
+- 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`
@@ -47,6 +47,7 @@ description:
 - `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
 
@@ -62,31 +63,39 @@ Use `defineOperation()` when an operation is large enough to live beside helper
 
 - `annotations`: `{ readOnly, destructive, idempotent, openWorld, rateLimit }` — agentic safety signals
 - `tags`: operation-level semantic tags for retrieval (e.g., `["weather", "korea", "realtime"]`)
-- `relatedOperations`: `{ alternatives?: string[]; chainsWith?: string[] }` — links to related operations for composite/fallback suggestions
-
-### Composite operations
-
-For multi-step chains (e.g., geocode → transform → forecast), use `defineCompositeOperation()` from `@apifuse/provider-sdk`:
-
-```ts
-import { defineCompositeOperation, z } from "@apifuse/provider-sdk"
-
-export const weatherByAddress = defineCompositeOperation({
-  id: "kma:weather-by-address",
-  description: "...",
-  input: z.object({ address: z.string().describe("...") }),
-  output: ResultSchema,
-  tags: ["weather", "korea", "composite"],
-  chainsWith: ["kakaomap:geocode", "kma:short-forecast"],
-  steps: async (ctx, input) => {
-    const geo = await ctx.chain.call("kakaomap:geocode", { address: input.address })
-    if (geo.items.length === 0) {
-      return ctx.clarify({ question: "...", missing: [{ name: "address", description: "..." }] })
-    }
-    // ... continue chain
-  },
-})
-```
+- `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.
+
+### Public local debugging checklist
+
+- Operation smoke requests use the provider server envelope:
+  `{"requestId":"req_local_<operation>","input":{...},"headers":{}}`.
+  Omit `connection` for public/no-auth operations; do not send `connection: null`.
+- Credential-backed smoke requests pass local-only credential material in
+  `connection.secrets`. Keep real values in shell env or `.env`, never in source
+  or fixtures.
+- Auth-flow debugging starts with `/auth/start`, continues with
+  `/auth/continue`, and carries returned `contextPatch` values into the next
+  request's `context`.
+- TLS/browser providers may require local runtime setup outside Provider code:
+  use `bun pm untrusted`/`bun pm trust koffi` for blocked native TLS dependency
+  scripts, `browser.engine: "playwright-stealth"` for TypeScript browser
+  Providers (`nodriver` is Python-runtime only), `bunx playwright install
+  chromium` for local Playwright browser assets, or
+  `CDP_POOL_URL`/`APIFUSE_CDP_POOL_URL` for remote browser debugging.
 
 ### Running the lint locally
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.2
+
+- Harden public bounty contributor DX with server-contract accurate README and generated Provider smoke examples.
+- Add packed-artifact regression checks so stale `connection: null` or missing `requestId` examples cannot ship again.
+- Extend clean-room packed SDK smoke coverage to boot the generated dev server and call `/health` plus `POST /v1/ping`.
+- Document credential, auth-flow, TLS, browser, and Bun trusted-dependency troubleshooting for SDK-only local development.
+
+## 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`.

package/README.md

@@ -8,12 +8,19 @@ ApiFuse Provider SDK — build provider declarations and runtimes with one publi
 bun add @apifuse/provider-sdk
 ```
 
+For external bounty scaffolding, use the beta tag until this release is promoted
+to `latest`:
+
+```bash
+bunx @apifuse/provider-sdk@beta create my-provider --yes
+```
+
 ## Create a provider
 
 ### Standalone (default)
 
 ```bash
-bunx @apifuse/provider-sdk create my-provider
+bunx @apifuse/provider-sdk@beta create my-provider --yes
 ```
 
 The canonical `create` flow:
@@ -49,11 +56,84 @@ Removed legacy runtime paths are not supported:
 
 ```bash
 cd my-provider
-bun run dev
 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 '{"requestId":"req_local_ping","input":{"value":"hello"},"headers":{}}'
 ```
 
+The operation request body is the same envelope used by the ApiFuse gateway:
+
+| Field | Required | Notes |
+|---|---:|---|
+| `requestId` | yes | Any unique string is fine for local debugging; it is echoed in structured errors. |
+| `input` | yes | The operation input after schema validation. |
+| `headers` | no | Extra caller headers to expose through `ctx.request.headers`. |
+| `connection` | no | Omit for no-auth/public operations. For credential debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+
+Credential-bearing local smoke example:
+
+```bash
+curl -s -X POST http://localhost:3900/v1/me \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "requestId":"req_local_me",
+    "input":{},
+    "connection":{
+      "id":"conn_local_debug",
+      "mode":"credentials",
+      "secrets":{"apiKey":"dev-only-secret"},
+      "scopes":[],
+      "metadata":{},
+      "externalRef":"local-debug"
+    }
+  }'
+```
+
+Auth-flow endpoints use the same `requestId` convention:
+
+```bash
+curl -s -X POST http://localhost:3900/auth/start \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_auth_start","flowId":"flow_local_1","providerId":"my-provider","context":{}}'
+```
+
+If a local smoke returns `{"error":...}`, inspect the JSON error body and the
+`apifuse dev` server log. Validation failures include a `details` array with
+the bad request path; provider/runtime failures include `code`, `message`, and
+`requestId`.
+
+### Local debugging checklist
+
+- **`invalid_request` on `/v1/{operation}`**: confirm the request body includes
+  `requestId` and `input`. Omit `connection` for public/no-auth operations;
+  never send `connection: null`.
+- **Credential-backed operations**: declare `credential.keys`, then pass matching
+  local-only values through `connection.secrets`. Read them in handlers with
+  `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
+- **Provider env secrets**: declare `secrets[]`, set values in your shell or
+  `.env`, and read only those names through `ctx.env.get("NAME")`.
+- **Auth flows**: call `/auth/start`, then `/auth/continue` with the same
+  `flowId`; preserve any returned `contextPatch` in the next local request's
+  `context` object.
+- **TLS-sensitive providers**: if Bun reports blocked lifecycle scripts after
+  install, run `bun pm untrusted`; when it lists trusted SDK native dependencies
+  such as `koffi`, run `bun pm trust koffi` (or `bun pm trust`) before debugging
+  `ctx.tls` failures.
+- **Browser providers**: for TypeScript Providers use `runtime: "browser"` plus
+  `browser.engine: "playwright-stealth"`; `nodriver` is a Python-runtime path.
+  Install local browser assets with `bunx playwright install chromium` when
+  using the Playwright runtime, or set `CDP_POOL_URL`/`APIFUSE_CDP_POOL_URL`
+  when debugging against a remote browser pool.
+
 ## Authoring ergonomics
 
 `defineProvider()` infers each operation handler input from the operation `input` schema. For larger providers, factor operations with `defineOperation()` and compose them later:
@@ -80,6 +160,18 @@ export default defineProvider({
 
 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.
+
 ### Operation annotations
 
 Operations declare non-functional metadata via `annotations`:
@@ -106,6 +198,11 @@ apifuse test [path]
 apifuse perf <path> --operation <operation>
 ```
 
+`apifuse record` is for real upstream-backed operations that declare
+`upstream.baseUrl` and call the upstream through `ctx.http` or `ctx.tls`. The
+generated local-only `ping` operation intentionally has no upstream and should
+be replaced before recording fixtures.
+
 ## Scope boundary
 
 Generator v1 scaffolds **TypeScript providers only** for this redesign. Python generation remains future work.
@@ -114,3 +211,8 @@ Generator v1 scaffolds **TypeScript providers only** for this redesign. Python g
 ## 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,13 +7,14 @@ import { pathToFileURL } from "node:url";
 import { z } from "zod";
 
 import type { ProviderDefinition } from "../src";
+import { lintProvider } from "../src/lint";
 import { safeParseSchemaSync } from "../src/schema";
 
 const HELP_TEXT = `Usage: apifuse check [path]
 Example: apifuse check providers/airkorea
 Default: apifuse check .`;
 
-type CheckResult = {
+export type CheckResult = {
 	message: string;
 	passed: boolean;
 	details?: string[];
@@ -103,7 +104,7 @@ function resolveFromParents(inputPath: string): string {
 	}
 }
 
-async function runChecks(providerRoot: string): Promise<CheckResult[]> {
+export async function runChecks(providerRoot: string): Promise<CheckResult[]> {
 	const indexPath = resolve(providerRoot, "index.ts");
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
@@ -118,6 +119,7 @@ async function runChecks(providerRoot: string): Promise<CheckResult[]> {
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
+		checkAuthoringLint(provider),
 		checkProviderMetadata(provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
@@ -254,6 +256,32 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 	};
 }
 
+function checkAuthoringLint(
+	provider: ProviderDefinition | undefined,
+): CheckResult {
+	if (!provider) {
+		return {
+			message: "Provider authoring lint has no error-level diagnostics",
+			passed: false,
+		};
+	}
+
+	const diagnostics = lintProvider(provider);
+	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,7 +1,7 @@
 #!/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 {
@@ -51,10 +51,24 @@ 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): {
@@ -111,8 +125,18 @@ 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.PORT ? `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 {

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,23 @@ if (!first) {
 }
 
 const filePaths = (first.files ?? []).map((file) => file.path);
+const requiredPaths = [
+	"bin/apifuse.ts",
+	"bin/apifuse-create.ts",
+	"bin/apifuse-pack-smoke.ts",
+	"src/cli/create.ts",
+	"src/cli/templates/provider/index.ts.tpl",
+	"src/cli/templates/provider/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 +53,85 @@ 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("bun pm untrusted")) {
+		throw new Error(
+			`${label} must include Bun trusted-dependency troubleshooting for TLS/browser bounties.`,
+		);
+	}
+
+	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.`,
+		);
+	}
+}