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

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";
@@ -25,7 +26,7 @@ import { createTraceContext } from "../runtime/trace.js";
 import { parseSchema } from "../schema.js";
 import { getStealthProfile } from "../stealth/profiles.js";
 import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream.js";
-import { createSelfTestApp, createSelfTestInvoke, resolveSelfTestPort } from "./self-test.js";
+import { createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, resolveSelfTestPort, } from "./self-test.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { AuthFlowRequestSchema, OperationRequestSchema, } from "./types.js";
 const DEFAULT_HOST = "0.0.0.0";
@@ -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",
@@ -1119,6 +1158,7 @@ export async function serve(provider, options = {}) {
         const selfTestApp = createSelfTestApp(provider, {
             secrets: selfTestSecrets,
             invoke: createSelfTestInvoke(app),
+            authFlow: createSelfTestAuthFlowInvoke(app),
         });
         bunRuntime.serve({
             port: options.selfTestPort ?? resolveSelfTestPort(),

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.4",
+	"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) {