@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/dist/ceremonies/index.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import Ajv2020 from "ajv/dist/2020.js";
-import { AUTH_TURN_SCHEMA } from "../auth-turn";
-import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors";
+import { AUTH_TURN_SCHEMA } from "../auth-turn/index.js";
+import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors.js";
 const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
 // Runtime ceremony-output validation derives from the exported versioned
 // contract: it compiles the exact AUTH_TURN_SCHEMA document shipped at
@@ -9,6 +9,15 @@ const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
 const validateAuthTurn = ajv.compile(AUTH_TURN_SCHEMA);
 const OAUTH2_STATE_KEY = "__oauth2_state";
 const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";
+export const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
+export const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
+const OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS = new Set([
+    "client_id",
+    "response_type",
+    "state",
+    "code_challenge",
+    "code_challenge_method",
+]);
 const DEVICE_FLOW_KEY = "__device_flow";
 const MAGIC_LINK_KEY = "__magic_link";
 const COMBINED_STAGE_KEY = "__combined_stage";
@@ -38,11 +47,7 @@ function getRequiredEnv(ctx, key) {
     return value;
 }
 function toBase64Url(input) {
-    return input
-        .toString("base64")
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=+$/g, "");
+    return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
 function createCodeVerifier() {
     return toBase64Url(randomBytes(32));
@@ -100,8 +105,7 @@ function withDeclaredFormFieldOrder(expectedInput) {
         return expectedInput;
     }
     const existingOrder = expectedInput[FORM_FIELD_ORDER_EXTENSION];
-    if (Array.isArray(existingOrder) &&
-        existingOrder.every((value) => typeof value === "string")) {
+    if (Array.isArray(existingOrder) && existingOrder.every((value) => typeof value === "string")) {
         return expectedInput;
     }
     return {
@@ -178,6 +182,54 @@ export function createOAuth2Ceremony(options) {
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
     };
 }
+/**
+ * Builds the start handler for a custom-scheme OAuth provider. The shared
+ * auth-proxy owns state minting and callback capture, while the provider owns
+ * token exchange and any following authentication turns.
+ */
+export function createOAuth2ProxiedStart(options) {
+    const pkce = options.pkce ?? "S256";
+    return (ctx) => runCeremonyHandler(async () => {
+        for (const key of Object.keys(options.authorizeParams ?? {})) {
+            if (OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())) {
+                throw new ValidationError(`OAuth2 proxied authorizeParams cannot override reserved parameter "${key}".`);
+            }
+        }
+        const proxyOrigin = ctx.env.get(OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY);
+        if (!proxyOrigin) {
+            throw new ProviderSecretError(`Missing required platform environment: ${OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY}`);
+        }
+        const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
+        if (!ctx.flowId) {
+            throw new ValidationError("OAuth2 proxied start requires the gateway flow id.");
+        }
+        const authorizePath = new URL(options.authorizeUrl).pathname;
+        const url = new URL(`/p/${encodeURIComponent(ctx.providerId)}/f/${encodeURIComponent(ctx.flowId)}${authorizePath}`, proxyOrigin);
+        url.searchParams.set("client_id", clientId);
+        url.searchParams.set("response_type", "code");
+        if (pkce === "S256") {
+            const verifier = createCodeVerifier();
+            ctx.context.set(OAUTH2_PROXIED_PKCE_VERIFIER_KEY, verifier);
+            url.searchParams.set("code_challenge", createCodeChallenge(verifier));
+            url.searchParams.set("code_challenge_method", "S256");
+        }
+        for (const [key, value] of Object.entries(options.authorizeParams ?? {})) {
+            url.searchParams.set(key, value);
+        }
+        return createTurn("redirect", {
+            data: { url: url.toString() },
+            hint: "Open the provider authorization page to continue.",
+            expectedInput: {
+                type: "object",
+                required: ["code", "state"],
+                properties: {
+                    code: { type: "string" },
+                    state: { type: "string" },
+                },
+            },
+        });
+    }, "OAuth2 proxied start failed", ctx);
+}
 export function createDeviceFlowCeremony(options) {
     return {
         start: (ctx) => runCeremonyHandler(async () => {
@@ -218,8 +270,7 @@ export function createDeviceFlowCeremony(options) {
             });
             const data = ensureRecord(response.data);
             const errorCode = getString(data, "error");
-            if (errorCode === "authorization_pending" ||
-                errorCode === "slow_down") {
+            if (errorCode === "authorization_pending" || errorCode === "slow_down") {
                 return createTurn("poll", {
                     data,
                     hint: "Authorization pending.",
@@ -345,7 +396,7 @@ export function createFormCeremony(options) {
     return {
         start: async () => validateCeremonyOutput(buildJsonSchemaForm(options.schema, options.hint ?? "Provide the required input to continue.")),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
-            const { prevalidate } = await import("../runtime/prevalidate");
+            const { prevalidate } = await import("../runtime/prevalidate.js");
             const result = prevalidate(options.schema, input);
             if (!result.valid) {
                 throw new ValidationError("Form input failed validation.", {
@@ -354,9 +405,7 @@ export function createFormCeremony(options) {
             }
             return createTurn("complete", {
                 data: {
-                    credential: options.mapCredential
-                        ? options.mapCredential(input)
-                        : input,
+                    credential: options.mapCredential ? options.mapCredential(input) : input,
                 },
                 hint: "Form completed.",
             });
@@ -428,9 +477,7 @@ export function createSwitchCeremony(options) {
         })),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const storedChoice = ctx.context.get(SWITCH_SELECTION_KEY);
-            const choice = typeof storedChoice === "string"
-                ? storedChoice
-                : getString(input, "choice");
+            const choice = typeof storedChoice === "string" ? storedChoice : getString(input, "choice");
             if (!choice || !options.choices[choice]) {
                 throw new ValidationError("A valid choice is required.");
             }

package/dist/cli/commands.d.ts

@@ -1,4 +1,4 @@
-export type ApifuseCommandName = "create" | "dev" | "check" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
+export type ApifuseCommandName = "create" | "dev" | "check" | "sync-assets" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
 export type ApifuseCommandManifest = {
     name: ApifuseCommandName;
     summary: string;

package/dist/cli/commands.js

@@ -23,6 +23,13 @@ export const COMMAND_MANIFEST = {
         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: "Score provider bounty submission readiness and emit checklist evidence.",
@@ -73,6 +80,7 @@ export const COMMAND_ORDER = [
     "create",
     "dev",
     "check",
+    "sync-assets",
     "submit-check",
     "record",
     "test",

package/dist/cli/create.d.ts

@@ -26,7 +26,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 = {
     displayName: string;

package/dist/cli/create.js

@@ -1,11 +1,12 @@
 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";
 import { cancel, intro, isCancel, note, outro, select, text } from "@clack/prompts";
 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 = [
     "developer-tools",
@@ -283,10 +284,15 @@ export async function buildProviderCreatePlan(options, cwd) {
     if (options.sdkSpecifier?.startsWith("workspace:") && !resolvedWorkspaceRoot) {
         throw new Error("workspace:* is only valid inside the APIFuse monorepo because public Provider SDK scaffolds must install from npm or an explicit tarball/file specifier.");
     }
+    // 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 = options.preset === "monorepo"
@@ -405,39 +411,21 @@ export async function buildProviderCreatePlan(options, cwd) {
                 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" } : {}),
+        });
+    }
+    // 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,
@@ -477,6 +465,7 @@ function renderPackageJson(input) {
             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",
@@ -696,6 +685,13 @@ function isApifuseInternalWorkspaceRoot(workspaceRoot) {
 async function writePlan(plan) {
     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);
     }
 }
@@ -754,7 +750,10 @@ function printResult(plan, jsonMode, dryRun) {
         },
         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) {
         console.log(JSON.stringify(payload, null, 2));

package/dist/cli/prompt-assets.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SDK-managed agent prompt assets.
+ *
+ * `apifuse create` scaffolds these files, `apifuse sync-assets` regenerates
+ * them in an existing provider root, and `apifuse check` / `submit-check`
+ * enforce that they byte-match the installed SDK version (fail closed).
+ *
+ * Layout contract:
+ * - AGENTS.md                     — real file (agent guide)
+ * - CLAUDE.md                     — symlink -> AGENTS.md
+ * - .agents/skills/<skill>/SKILL.md — real files
+ * - .agents/skills/upstream-notes/README.md — real file
+ * - .claude / .codex              — symlinks -> .agents
+ * - .apifuse/prompt-assets.json   — manifest (schema v2), written last
+ */
+export declare const PROMPT_ASSET_MANIFEST_PATH = ".apifuse/prompt-assets.json";
+export declare const PROMPT_ASSET_MANIFEST_SCHEMA_VERSION = 2;
+export declare const PROMPT_ASSET_SYNC_REMEDIATION = "Run `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate the SDK-managed agent prompt assets.";
+export declare const PROMPT_ASSET_SYMLINKS: Readonly<Record<string, string>>;
+/** Relative asset paths whose content is rendered from `<path>.tpl`. */
+export declare const PROMPT_ASSET_FILE_PATHS: readonly string[];
+export type PromptAssetKind = "file" | "symlink";
+export type PromptAssetEntry = {
+    /** Provider-root-relative path (POSIX separators). */
+    path: string;
+    /** File content, or the symlink target for kind "symlink". */
+    content: string;
+    kind: PromptAssetKind;
+};
+export type PromptAssetTemplateRenderer = (fileName: string, values: Record<string, string>) => string | Promise<string>;
+export type PromptAssetVerification = {
+    ok: boolean;
+    /** Expected paths (or the manifest) absent on disk. */
+    missing: string[];
+    /** Manifest recorded for a different SDK version than the installed one. */
+    stale: string[];
+    /** Files/symlinks/manifest whose bytes or target differ from the regenerated set. */
+    modified: string[];
+    /** Legacy layout remnants (top-level skills/). */
+    legacy: string[];
+    /** Entries inside `.agents/` that are not part of the managed asset set. */
+    unexpected: string[];
+};
+export type PromptAssetSyncResult = {
+    changed: boolean;
+    removed: string[];
+    wroteFiles: string[];
+    createdSymlinks: string[];
+    manifestPath: string;
+};
+/**
+ * Build the full managed asset entry list (files first, symlinks after,
+ * manifest excluded). The renderer is injected so `apifuse create` can reuse
+ * its own template renderer; sync/verify use the SDK-internal renderer.
+ */
+export declare function buildPromptAssetPlanEntries(renderTemplate: PromptAssetTemplateRenderer): Promise<PromptAssetEntry[]>;
+export declare function buildPromptAssetPlanEntriesSync(): PromptAssetEntry[];
+/**
+ * Deterministic manifest serialization: schema v2, 2-space JSON, trailing
+ * newline, sorted paths (including symlink paths, excluding the manifest
+ * itself). `sdkVersion` + `paths` keep their v1 semantics so older parsers
+ * keep working; `schemaVersion` and `symlinks` are additive.
+ */
+export declare function buildPromptAssetManifest(entries: readonly PromptAssetEntry[], sdkVersion: string): string;
+export declare function installedSdkVersion(): string;
+/**
+ * Verify the on-disk prompt assets against the set regenerated from the
+ * installed SDK. Uses lstat/readlink for symlinks (never follows), byte
+ * comparison for files, and exact-version comparison for the manifest.
+ */
+export declare function verifyPromptAssets(providerRoot: string): PromptAssetVerification;
+export declare function formatPromptAssetIssues(verification: PromptAssetVerification): string[];
+/**
+ * Regenerate the full managed asset set for the installed SDK version in an
+ * existing provider root. Deletes legacy managed paths first (top-level
+ * skills/**, plus manifest-listed paths that left the set — restricted to
+ * managed namespaces with no symlinked ancestors), writes files, replaces
+ * symlinks, and writes the manifest last. Idempotent.
+ */
+export declare function syncPromptAssets(providerRoot: string): PromptAssetSyncResult;