@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.7

package/dist/cli/templates/provider/AGENTS.md.tpl

@@ -4,8 +4,8 @@ You are building an APIFuse provider. APIFuse turns messy upstream APIs into
 normalized, typed, evidence-backed public APIs. A provider that merely proxies
 the upstream is a failed provider, even if every check passes.
 
-This file is the core contract. Detailed procedures live in `skills/` — load
-the matching skill BEFORE working on that area (index at the bottom).
+This file is the core contract. Detailed procedures live in `.agents/skills/` —
+load the matching skill BEFORE working on that area (index at the bottom).
 
 ## Non-negotiable principles
 
@@ -75,13 +75,22 @@ bun run submit-check # structural score; a high score does NOT prove quality
 `submit-check` is a structural gate. Every principle above can be violated
 while scoring 95/100 — reviewers and CI audit for exactly these classes.
 
+## Managed prompt assets
+
+`AGENTS.md` and `.agents/skills/**` are generated by the SDK; `CLAUDE.md`,
+`.claude`, and `.codex` are symlinks onto them so every agent CLI reads the
+same contract. Do not hand-edit these files — regenerate them with
+`bun run sync-assets` (or `bunx apifuse sync-assets .`). `apifuse check` and
+`submit-check` enforce a freshness gate: stale or modified prompt assets
+(tracked in `.apifuse/prompt-assets.json`) block submission until re-synced.
+
 ## Skill index — load before working on:
 
 | Area | Load |
 | --- | --- |
-| Output schemas, mappers, field naming, timestamps, enums | `skills/normalization-standards/SKILL.md` |
-| Upstream request params, new endpoint wiring, field mapping | `skills/upstream-contract-verification/SKILL.md` |
-| Recording fixtures, writing tests against fixtures | `skills/fixtures-and-recording/SKILL.md` |
-| List operations, paging, totals, client-side filtering | `skills/pagination-and-counts/SKILL.md` |
-| healthCheck blocks, error classification, fail-closed guards | `skills/health-checks-and-fail-closed/SKILL.md` |
-| Upstream-specific known pitfalls for THIS bounty | `skills/upstream-notes/` (read every file) |
+| Output schemas, mappers, field naming, timestamps, enums | `.agents/skills/normalization-standards/SKILL.md` |
+| Upstream request params, new endpoint wiring, field mapping | `.agents/skills/upstream-contract-verification/SKILL.md` |
+| Recording fixtures, writing tests against fixtures | `.agents/skills/fixtures-and-recording/SKILL.md` |
+| List operations, paging, totals, client-side filtering | `.agents/skills/pagination-and-counts/SKILL.md` |
+| healthCheck blocks, error classification, fail-closed guards | `.agents/skills/health-checks-and-fail-closed/SKILL.md` |
+| Upstream-specific known pitfalls for THIS bounty | `.agents/skills/upstream-notes/` (read every file) |

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { generateInsights } from "./runtime/insights.js";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";

package/dist/index.js

@@ -24,6 +24,7 @@ export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";

package/dist/runtime/executor.js

@@ -1,5 +1,6 @@
 import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
 import { parseSchema } from "../schema.js";
+import { assertRequiredSecretsPresent } from "./secrets.js";
 export function isStreamingOperation(provider, operationId) {
     const kind = provider.operations[operationId]?.transport?.kind ?? "json";
     return kind !== "json";
@@ -23,6 +24,12 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
             fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
         });
     }
+    // SDK-owned secret presence gate (single source of truth): declared
+    // `required: true` secrets are validated here, before input parsing and the
+    // handler, so every invocation path (serve /v1, self-test probes, perf,
+    // record) fails with the same structured MISSING_SECRET error instead of a
+    // handler-specific crash. Providers must not re-check presence locally.
+    assertRequiredSecretsPresent(provider, ctx.env);
     const validatedInput = await parseSchema(operation.input, input, `operations.${operationId}.input`);
     const execute = () => ctx.trace.span(`handler:${operationId}`, () => Promise.resolve(operation.handler(ctx, validatedInput)));
     let result;

package/dist/runtime/secrets.d.ts

@@ -0,0 +1,27 @@
+import type { EnvContext, ProviderDefinition } from "../types.js";
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export declare const MISSING_SECRET_CODE = "MISSING_SECRET";
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export declare function listMissingRequiredSecrets(provider: ProviderDefinition, env: EnvContext): string[];
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export declare function assertRequiredSecretsPresent(provider: ProviderDefinition, env: EnvContext): void;

package/dist/runtime/secrets.js

@@ -0,0 +1,51 @@
+import { ProviderSecretError } from "../errors.js";
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export const MISSING_SECRET_CODE = "MISSING_SECRET";
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export function listMissingRequiredSecrets(provider, env) {
+    const missing = [];
+    for (const secret of provider.secrets ?? []) {
+        if (secret.required !== true) {
+            continue;
+        }
+        const value = env.get(secret.name);
+        if (value === undefined || value.trim() === "") {
+            missing.push(secret.name);
+        }
+    }
+    return missing;
+}
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export function assertRequiredSecretsPresent(provider, env) {
+    const missing = listMissingRequiredSecrets(provider, env);
+    if (missing.length === 0) {
+        return;
+    }
+    const names = missing.join(", ");
+    throw new ProviderSecretError(`Missing required provider secret${missing.length > 1 ? "s" : ""}: ${names}`, {
+        code: MISSING_SECRET_CODE,
+        category: "credential_unavailable",
+        retryable: false,
+        fix: `Provision ${names} in the provider environment (e.g. Doppler). Declared in defineProvider({ secrets: [...] }).`,
+    });
+}

package/dist/server/serve.d.ts

@@ -35,6 +35,11 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
         message: string;
     }>;
 }) | {
+    level: "warn";
+    event: "provider_secrets_missing";
+    providerId: string;
+    missingSecrets: string[];
+} | {
     level: "warn";
     event: "provider_cleanup_failed";
     providerId: string;

package/dist/server/serve.js

@@ -18,6 +18,7 @@ import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
+import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
 import { createStealthClient } from "../runtime/stealth.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
@@ -357,6 +358,18 @@ function providerObservabilityDetails(error) {
             retryable: error.options?.retryable ?? false,
         };
     }
+    // Missing-secret errors carry the canonical credential_unavailable category
+    // so Gateway/observability can attribute the failure to provisioning, not
+    // the upstream. Matched by code (not constructor) so both the SDK-owned
+    // runtime gate and any not-yet-migrated provider-thrown MISSING_SECRET
+    // serialize identically, including across duplicate SDK module instances.
+    if (isProviderError(error) && error.code === MISSING_SECRET_CODE) {
+        return {
+            category: error.options?.category ?? "credential_unavailable",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: error.options?.retryable ?? false,
+        };
+    }
     if (!isTransportError(error)) {
         return undefined;
     }
@@ -422,6 +435,10 @@ function toStatusCode(error) {
             case "AUTH_REQUIRED":
             case "reauth_required":
                 return 401;
+            // Unprovisioned declared secret: a deployment/config defect, never an
+            // upstream failure — explicit 400 (was only reached via fallthrough).
+            case MISSING_SECRET_CODE:
+                return 400;
             case "NOT_FOUND":
             case "not_found":
             case "NO_DATA":
@@ -885,8 +902,16 @@ async function handleAuthFlow(provider, request, route, options = {}, signal) {
             code: "AUTH_FLOW_NOT_CONFIGURED",
         });
     }
+    // Same SDK-owned gate as executeOperation: OAuth/credentials ceremonies
+    // depend on declared secrets (client ids/secrets), so fail structured before
+    // any flow code runs instead of at whatever point the ceremony first reads
+    // the env. `abort` stays exempt: a user must always be able to cancel a
+    // stranded flow even when provisioning is broken.
     const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
     try {
+        if (route !== "abort") {
+            assertRequiredSecretsPresent(provider, context.env);
+        }
         const result = route === "start"
             ? await flow.start(context)
             : route === "continue"
@@ -933,6 +958,20 @@ export function createServerApp(provider, options = {}) {
             providerId: provider.id,
             allowMemoryFallback: options.allowMemoryStateFallback === true,
         });
+    // Boot-time visibility for unprovisioned declared secrets: emit a structured
+    // warn so deploy tooling/alerting sees the gap the moment the pod boots,
+    // instead of discovering it request-by-request. Deliberately log-only — a
+    // boot crash would trade a structured MISSING_SECRET signal for
+    // CrashLoopBackOff. Requests still fail closed via the executeOperation gate.
+    const missingSecretsAtBoot = listMissingRequiredSecrets(provider, createEnvContext(provider.secrets?.map((secret) => secret.name)));
+    if (missingSecretsAtBoot.length > 0) {
+        logger({
+            level: "warn",
+            event: "provider_secrets_missing",
+            providerId: provider.id,
+            missingSecrets: missingSecretsAtBoot,
+        });
+    }
     app.notFound((c) => c.json({
         error: {
             code: "not_found",

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.5",
+	"version": "2.2.0-beta.7",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/cli/commands.ts

@@ -2,6 +2,7 @@ export type ApifuseCommandName =
 	| "create"
 	| "dev"
 	| "check"
+	| "sync-assets"
 	| "submit-check"
 	| "bounty-check"
 	| "record"
@@ -46,6 +47,14 @@ export const COMMAND_MANIFEST: Record<
 		examples: ["apifuse check .", "apifuse check providers/korea-air-quality"],
 		modulePath: "./apifuse-check",
 	},
+	"sync-assets": {
+		name: "sync-assets",
+		summary:
+			"Regenerate SDK-managed agent prompt assets (AGENTS.md, .agents/skills, symlinks, manifest) for the installed SDK version.",
+		usage: "apifuse sync-assets [path] [--check]",
+		examples: ["apifuse sync-assets .", "apifuse sync-assets . --check"],
+		modulePath: "./apifuse-sync-assets",
+	},
 	"submit-check": {
 		name: "submit-check",
 		summary:
@@ -103,6 +112,7 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"create",
 	"dev",
 	"check",
+	"sync-assets",
 	"submit-check",
 	"record",
 	"test",

package/src/cli/create.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -8,6 +8,11 @@ import { cancel, intro, isCancel, note, outro, select, text } from "@clack/promp
 import { z } from "zod";
 
 import packageJson from "../../package.json";
+import {
+	buildPromptAssetManifest,
+	buildPromptAssetPlanEntries,
+	PROMPT_ASSET_MANIFEST_PATH,
+} from "./prompt-assets.js";
 
 export const PROVIDER_NAME_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 export const CATEGORY_OPTIONS = [
@@ -64,7 +69,10 @@ export type CreateResolvedOptions = {
 
 export type ProviderPlanFile = {
 	path: string;
+	/** File content, or the symlink target (relative path) for kind "symlink". */
 	content: string;
+	/** Absent kind means "file" (backward compatible with older consumers). */
+	kind?: "file" | "symlink";
 };
 
 export type ProviderCreatePlan = {
@@ -410,11 +418,16 @@ export async function buildProviderCreatePlan(
 		);
 	}
 
+	// Exact pin, not a caret range: the prompt-asset freshness gate requires
+	// manifest.sdkVersion === installed SDK version, and the manifest records
+	// this CLI's own version. A caret range would let `bun install` resolve a
+	// newer SDK than the create binary, making a fresh scaffold fail its own
+	// gate. `sync-assets` after an explicit SDK upgrade re-records the version.
 	const sdkSpecifier =
 		options.sdkSpecifier ??
 		(options.preset === "monorepo" && resolvedWorkspaceRoot
 			? "workspace:*"
-			: `^${packageJson.version}`);
+			: packageJson.version);
 	const relativeProviderRoot = relative(cwd, providerRoot) || options.name;
 	const nextDevCommand = `cd ${relativeProviderRoot} && bun run dev`;
 	const packageName =
@@ -538,40 +551,23 @@ export async function buildProviderCreatePlan(
 				PROVIDER_ID: options.name,
 			}),
 		},
-		{
-			path: resolve(providerRoot, "AGENTS.md"),
-			content: await renderTemplate("AGENTS.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "CLAUDE.md"),
-			content: await renderTemplate("CLAUDE.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "normalization-standards", "SKILL.md"),
-			content: await renderTemplate("skills/normalization-standards/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "upstream-contract-verification", "SKILL.md"),
-			content: await renderTemplate("skills/upstream-contract-verification/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "fixtures-and-recording", "SKILL.md"),
-			content: await renderTemplate("skills/fixtures-and-recording/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "pagination-and-counts", "SKILL.md"),
-			content: await renderTemplate("skills/pagination-and-counts/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "health-checks-and-fail-closed", "SKILL.md"),
-			content: await renderTemplate("skills/health-checks-and-fail-closed/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "upstream-notes", "README.md"),
-			content: await renderTemplate("skills/upstream-notes/README.md.tpl", {}),
-		},
 	];
 
+	const promptAssetEntries = await buildPromptAssetPlanEntries(renderTemplate);
+	for (const entry of promptAssetEntries) {
+		files.push({
+			path: resolve(providerRoot, entry.path),
+			content: entry.content,
+			...(entry.kind === "symlink" ? { kind: "symlink" as const } : {}),
+		});
+	}
+	// Manifest last: writePlan writes in order, so a crash mid-scaffold never
+	// leaves a manifest that claims assets which were not written.
+	files.push({
+		path: resolve(providerRoot, PROMPT_ASSET_MANIFEST_PATH),
+		content: buildPromptAssetManifest(promptAssetEntries, packageJson.version),
+	});
+
 	return {
 		displayName: options.displayName,
 		files,
@@ -614,6 +610,7 @@ function renderPackageJson(input: { packageName: string; sdkSpecifier: string })
 				check: "apifuse check . && bun run type-check",
 				"type-check": "tsc --noEmit",
 				"submit-check": "apifuse submit-check . --markdown submission-report.md",
+				"sync-assets": "apifuse sync-assets .",
 				test: "apifuse test .",
 				record: "apifuse record .",
 				start: "bun start.ts",
@@ -869,6 +866,13 @@ function isApifuseInternalWorkspaceRoot(workspaceRoot: string): boolean {
 async function writePlan(plan: ProviderCreatePlan): Promise<void> {
 	for (const file of plan.files) {
 		await mkdir(dirname(file.path), { recursive: true });
+		if (file.kind === "symlink") {
+			// rm operates on the link itself (lstat semantics) and tolerates
+			// directories, so whatever occupies the path is replaced by the link.
+			await rm(file.path, { recursive: true, force: true });
+			await symlink(file.content, file.path);
+			continue;
+		}
 		await writeFile(file.path, file.content);
 	}
 }
@@ -940,7 +944,10 @@ function printResult(plan: ProviderCreatePlan, jsonMode: boolean, dryRun: boolea
 		},
 		validationCommands: plan.validationCommands,
 		nextDevCommand: plan.nextDevCommand,
-		files: plan.files.map((file) => relative(plan.providerRoot, file.path) || file.path),
+		files: plan.files.map((file) => {
+			const relativePath = relative(plan.providerRoot, file.path) || file.path;
+			return file.kind === "symlink" ? `${relativePath} -> ${file.content} (symlink)` : relativePath;
+		}),
 	};
 
 	if (jsonMode) {