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

package/AUTHORING.md

@@ -74,6 +74,7 @@ External contributors are expected to submit standalone Provider source plus:
 - Health coverage table for every Operation.
 - `bun run check` output.
 - `bun run test` output.
+- `bun run submit-check` score/verdict and generated `submission-report.md`.
 - Fixture evidence and known upstream constraints.
 
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
@@ -97,6 +98,14 @@ deployment projection checks, and release workflows.
   chromium` for local Playwright browser assets, or
   `CDP_POOL_URL`/`APIFUSE_CDP_POOL_URL` for remote browser debugging.
 
+### Running the pre-submission report
+
+```bash
+bun run submit-check
+```
+
+The report scores review readiness across definition metadata, operation/schema quality, fixtures/tests, health coverage, local smoke evidence, auth safety, secret hygiene, and submission docs. It is not a payout guarantee; any blocker must be fixed before review. For the complete public-only submission checklist, see `SUBMISSION.md` in the SDK package.
+
 ### Running the lint locally
 
 ```bash

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.3
+
+- Add the public `apifuse submit-check` / `apifuse bounty-check` CLI for score-based pre-submission provider quality checks.
+- Ship `SUBMISSION.md` in the npm package so bounty contributors can follow the checklist without access to the private monorepo.
+- Include submit-check in generated provider validation scripts and packed-artifact smoke coverage.
+- Warn, instead of hard-block, generated OAuth starters that have not yet declared persisted credential keys.
+
 ## 2.1.0-beta.2
 
 - Harden public bounty contributor DX with server-contract accurate README and generated Provider smoke examples.

package/README.md

@@ -58,6 +58,7 @@ Removed legacy runtime paths are not supported:
 cd my-provider
 bun run check
 bun run test
+bun run submit-check
 bun run dev
 ```
 
@@ -195,6 +196,8 @@ apifuse dev [path]
 apifuse check [path]
 apifuse record [path] --operation <operation> --params '{"value":"hello"}'
 apifuse test [path]
+apifuse submit-check [path] --tier bronze --markdown submission-report.md
+apifuse bounty-check [path]
 apifuse perf <path> --operation <operation>
 ```
 
@@ -203,6 +206,16 @@ apifuse perf <path> --operation <operation>
 generated local-only `ping` operation intentionally has no upstream and should
 be replaced before recording fixtures.
 
+## Bounty submission readiness
+
+Standalone providers include a pre-submission script:
+
+```bash
+bun run submit-check
+```
+
+This runs the public review-readiness evaluator and writes `submission-report.md`. The report contains provider metadata, a 100-point readiness score, hard blockers, warnings, checklist evidence, and remediation. Blockers override the score; fix them before posting bounty evidence. The command is offline-safe by default and does not execute arbitrary upstream calls. Add local smoke notes to your bounty issue after testing `/health` and `POST /v1/{operation}`. See [`SUBMISSION.md`](./SUBMISSION.md) for the full public-only bounty submission checklist shipped in the npm package.
+
 ## Scope boundary
 
 Generator v1 scaffolds **TypeScript providers only** for this redesign. Python generation remains future work.

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.
+
+## Public-only workflow
+
+```bash
+bunx @apifuse/provider-sdk@beta create my-provider --yes
+cd my-provider
+bun run check
+bun run test
+bun run submit-check
+bun run dev
+```
+
+`bun run submit-check` runs `apifuse submit-check . --markdown submission-report.md` in generated Providers.
+
+## 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.
+
+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.
+
+## Safe local smoke evidence
+
+`submit-check` does not call arbitrary live upstream APIs by default. After replacing starter logic, run the Provider locally and record a short evidence note:
+
+```bash
+bun run dev
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/<operation> \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_local_smoke","input":{...},"headers":{}}'
+
+bun run submit-check -- --smoke-note "GET /health and POST /v1/<operation> passed locally with redacted input."
+```
+
+Never paste real credentials, personal data, account numbers, access tokens, cookies, or unredacted upstream responses into issue comments 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 public 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. Public contributors are not expected to run those private checks.

package/bin/apifuse-pack-check.ts

@@ -33,6 +33,8 @@ 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/index.ts.tpl",
 	"src/cli/templates/provider/README.md.tpl",
@@ -117,6 +119,12 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
+	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")

package/bin/apifuse-pack-smoke.ts

@@ -93,6 +93,7 @@ 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);
@@ -166,6 +167,11 @@ function assertGeneratedReadme(providerDir: string): void {
 			"Generated README is missing Bun trusted-dependency troubleshooting 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>")) {
 		throw new Error(
 			"Generated README must document fixture recording through the generated record script.",