@apifuse/provider-sdk 2.2.0-beta.41 → 2.2.0-beta.42

package/dist/cli/migrate-operation-shape.js

@@ -0,0 +1,113 @@
+const ts = await loadTypeScript();
+async function loadTypeScript() {
+    try {
+        return await import("typescript");
+    }
+    catch {
+        console.error("apifuse migrate-shape requires typescript; install it in the workspace running the CLI (bun add -d typescript)");
+        process.exit(1);
+    }
+}
+const OPERATION_HELPERS = new Set(["defineOperation", "defineStreamOperation"]);
+const PROVIDER_CONTEXT_TYPE_NAME = "ProviderContext";
+const PROVIDER_SDK_PROVIDER_SUBPATH = "@apifuse/provider-sdk/provider";
+/**
+ * Migrate legacy `defineOperation(config)` calls in one source file to the
+ * curried `defineOperation<ProviderContext>()(config)` form.
+ *
+ * @param contextImportSpecifier module specifier the `ProviderContext` type
+ * import should come from when one has to be added — `"../index"` for
+ * operation modules, `"./index"` is never needed because index.ts declares
+ * the alias itself. Callers pass the correct relative path per file.
+ */
+export function migrateOperationShape(sourceText, fileName, contextImportSpecifier) {
+    const source = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const parseError = firstSyntaxError(source);
+    if (parseError !== undefined) {
+        return { status: "skipped", reason: parseError };
+    }
+    // Every legacy call site: a direct call to the bare helper identifier
+    // whose single argument is the config (i.e. NOT the curried form, whose
+    // outer call has zero arguments and optional type arguments).
+    const legacyCalls = [];
+    let sawCurried = false;
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            OPERATION_HELPERS.has(node.expression.text)) {
+            if (node.arguments.length === 0) {
+                sawCurried = true; // already-migrated outer call
+            }
+            else {
+                legacyCalls.push(node);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (legacyCalls.length === 0) {
+        return { status: "unchanged", code: sourceText };
+    }
+    // A file mixing both forms almost certainly had a partial hand-migration;
+    // refuse rather than guess which convention the author wants.
+    if (sawCurried) {
+        return {
+            status: "skipped",
+            reason: "File mixes legacy defineOperation(config) with curried defineOperation<...>()(config); migrate it by hand.",
+        };
+    }
+    const declaresContextAlias = source.statements.some((statement) => ts.isTypeAliasDeclaration(statement) &&
+        statement.name.text === PROVIDER_CONTEXT_TYPE_NAME);
+    const importsContext = sourceText.includes(PROVIDER_CONTEXT_TYPE_NAME);
+    const needsImport = !declaresContextAlias && !importsContext;
+    const edits = [];
+    for (const call of legacyCalls) {
+        // `defineOperation(` -> `defineOperation<ProviderContext>()(`
+        const callee = call.expression;
+        edits.push({
+            start: callee.getEnd(),
+            end: callee.getEnd(),
+            text: `<${PROVIDER_CONTEXT_TYPE_NAME}>()`,
+        });
+    }
+    let importAdded = false;
+    if (needsImport) {
+        const lastImport = [...source.statements]
+            .reverse()
+            .find((statement) => ts.isImportDeclaration(statement));
+        const insertAt = lastImport ? lastImport.getEnd() : 0;
+        const importText = `${lastImport ? "\n" : ""}import type { ${PROVIDER_CONTEXT_TYPE_NAME} } from "${contextImportSpecifier}";${lastImport ? "" : "\n"}`;
+        edits.push({ start: insertAt, end: insertAt, text: importText });
+        importAdded = true;
+    }
+    const ordered = edits.sort((a, b) => b.start - a.start);
+    let code = sourceText;
+    for (const edit of ordered) {
+        code = code.slice(0, edit.start) + edit.text + code.slice(edit.end);
+    }
+    const verified = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const outputError = firstSyntaxError(verified);
+    if (outputError !== undefined) {
+        return {
+            status: "skipped",
+            reason: `Transform produced source that does not parse (${outputError}); refusing to emit a partial migration.`,
+        };
+    }
+    return {
+        status: "migrated",
+        code,
+        rewrites: legacyCalls.length,
+        importAdded,
+    };
+}
+function firstSyntaxError(source) {
+    const diagnostics = source.parseDiagnostics;
+    if (diagnostics === undefined || diagnostics.length === 0)
+        return undefined;
+    const first = diagnostics[0];
+    if (first === undefined)
+        return undefined;
+    const message = ts.flattenDiagnosticMessageText(first.messageText, " ");
+    const { line } = source.getLineAndCharacterOfPosition(first.start);
+    return `${message} (line ${line + 1})`;
+}

package/dist/cli/migrate-provider-shape.js

@@ -1,4 +1,13 @@
-import ts from "typescript";
+const ts = await loadTypeScript();
+async function loadTypeScript() {
+    try {
+        return await import("typescript");
+    }
+    catch {
+        console.error("apifuse migrate-shape requires typescript; install it in the workspace running the CLI (bun add -d typescript)");
+        process.exit(1);
+    }
+}
 const DECLARATION_BUILDER_NAME = "buildProvider";
 const PROVIDER_CONTEXT_TYPE_NAME = "ProviderContext";
 const PROVIDER_CONTEXT_OF_TYPE_NAME = "ProviderContextOf";
@@ -397,6 +406,12 @@ function ensureProviderContextType(source, call, shape, builderName) {
     const edits = [];
     const hasContextTypeAlias = source.statements.some((statement) => ts.isTypeAliasDeclaration(statement) &&
         statement.name.text === PROVIDER_CONTEXT_TYPE_NAME);
+    // A named import of `ProviderContext` (the deprecated SDK-root context
+    // type, imported by legacy sources) occupies the same name: adding the
+    // alias alongside it is TS2440. The import must yield to the derived
+    // alias — the whole point of the two-phase shape — so drop it and let the
+    // alias own the name.
+    const conflictingImportSpecifier = findNamedImportSpecifier(source, PROVIDER_CONTEXT_TYPE_NAME);
     if (!hasContextTypeAlias) {
         // After the builder statement — which is the variable statement when the
         // declaration was bound, or the rewritten export statement otherwise.
@@ -409,6 +424,9 @@ function ensureProviderContextType(source, call, shape, builderName) {
                 end: insertAt,
                 text: `\n\nexport type ${PROVIDER_CONTEXT_TYPE_NAME} = ${PROVIDER_CONTEXT_OF_TYPE_NAME}<typeof ${builderName}>;`,
             });
+            if (conflictingImportSpecifier !== undefined) {
+                edits.push(removeImportSpecifier(source, conflictingImportSpecifier));
+            }
         }
     }
     if (text.includes(PROVIDER_CONTEXT_OF_TYPE_NAME)) {
@@ -454,6 +472,51 @@ function findProviderSdkImport(source) {
     }
     return undefined;
 }
+/** Named import specifier binding `localName` in any import declaration. */
+function findNamedImportSpecifier(source, localName) {
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const named = statement.importClause?.namedBindings;
+        if (named === undefined || !ts.isNamedImports(named))
+            continue;
+        for (const element of named.elements) {
+            if (element.name.text === localName)
+                return element;
+        }
+    }
+    return undefined;
+}
+/**
+ * Edit removing one specifier from its named-import list, absorbing one
+ * neighboring comma so the list stays well-formed. Callers guarantee the
+ * list has at least one other specifier (legacy sources always import
+ * defineProvider alongside the context type).
+ */
+function removeImportSpecifier(source, specifier) {
+    const list = specifier.parent;
+    const index = list.elements.indexOf(specifier);
+    const text = source.getFullText();
+    let start = specifier.getFullStart();
+    let end = specifier.getEnd();
+    let cursor = end;
+    while (cursor < text.length && /\s/.test(text.charAt(cursor)))
+        cursor += 1;
+    if (text.charAt(cursor) === ",") {
+        end = cursor + 1;
+    }
+    else if (index > 0) {
+        const previous = list.elements[index - 1];
+        if (previous !== undefined) {
+            let back = previous.getEnd();
+            while (back < text.length && /\s/.test(text.charAt(back)))
+                back += 1;
+            if (text.charAt(back) === ",")
+                start = back;
+        }
+    }
+    return { start, end, text: "" };
+}
 /**
  * `buildProvider` unless the module already binds that name, in which case a
  * numbered suffix keeps the transform from shadowing an existing binding.

package/dist/server/serve-implementation.js

@@ -9,7 +9,7 @@ import { validateFailClosedDeclaration } from "../declaration-validation.js";
 import { safeProviderErrorObservability } from "../error-observability.js";
 import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
-import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
+import { REDACTED_FIXTURE_VALUE, sanitizeDiagnosticText, } from "../fixture-sanitization.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, sourceForCategory, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
@@ -979,8 +979,47 @@ function extractRequestId(raw) {
 }
 const MAX_PROVIDER_ERROR_CAUSE_FRAMES = 5;
 const MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH = 300;
+const UNSTRUCTURED_PROVIDER_ERROR_CAUSE_MESSAGE = "[UNSTRUCTURED_UPSTREAM_TEXT]";
+const PROVIDER_ERROR_CAUSE_RETAINED_URL_RUN = /https?:\/\/[^\s"'<>]+/giu;
+const PROVIDER_ERROR_CAUSE_TOKEN_RUN = /\S+/gu;
+const PROVIDER_ERROR_CAUSE_TOKEN_EDGE_PUNCTUATION = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu;
+const STRUCTURALLY_SAFE_PROVIDER_ERROR_CAUSE_WORDS = new Set([
+    "completion",
+    "diagnostic",
+    "provider",
+    "rejected",
+    "returned",
+    "upstream",
+]);
+/**
+ * Cause frames fail closed when sanitization leaves a plausible credential-shaped free-text run.
+ * Redaction sentinels and retained URLs are ignored. Every other whitespace token (or each side
+ * of a structured key=value token) with at least eight Unicode characters must reduce to this
+ * small vocabulary drawn from SDK diagnostics; counting punctuation keeps bare passwords opaque.
+ */
+function isStructurallySafeProviderErrorCauseMessage(message) {
+    const classifiableMessage = message
+        .replaceAll(REDACTED_FIXTURE_VALUE, " ")
+        .replace(PROVIDER_ERROR_CAUSE_RETAINED_URL_RUN, " ");
+    for (const match of classifiableMessage.matchAll(PROVIDER_ERROR_CAUSE_TOKEN_RUN)) {
+        const token = match[0];
+        for (const run of token.split("=")) {
+            const diagnosticWord = run
+                .replace(PROVIDER_ERROR_CAUSE_TOKEN_EDGE_PUNCTUATION, "")
+                .toLowerCase();
+            if (STRUCTURALLY_SAFE_PROVIDER_ERROR_CAUSE_WORDS.has(diagnosticWord))
+                continue;
+            if ([...run].length >= 8)
+                return false;
+        }
+    }
+    return true;
+}
 function providerErrorCauseMessage(message) {
     const sanitized = sanitizeDiagnosticText(message);
+    if (!isStructurallySafeProviderErrorCauseMessage(sanitized)) {
+        return UNSTRUCTURED_PROVIDER_ERROR_CAUSE_MESSAGE;
+    }
     return sanitized.length > MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH
         ? `${sanitized.slice(0, MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH)}… [truncated]`
         : sanitized;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.41",
+	"version": "2.2.0-beta.42",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -128,7 +128,8 @@
 		"@microsoft/api-extractor": "^7.58.13",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"ajv": "^8.17"
+		"ajv": "^8.17",
+		"typescript": "6.0.3"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
@@ -145,7 +146,6 @@
 		"safe-regex": "^2.1",
 		"socks": "^2.8.9",
 		"tough-cookie": "^6.0.2",
-		"typescript": "6.0.3",
 		"wreq-js": "3.0.0",
 		"zod": "^4.4.3"
 	},

package/src/cli/commands.ts

@@ -59,7 +59,7 @@ export const COMMAND_MANIFEST: Record<
 	"migrate-shape": {
 		name: "migrate-shape",
 		summary:
-			"Migrate a provider index.ts from the single-phase defineProvider shape to the two-phase declaration builder.",
+			"Migrate a provider to the phase-separated SDK: two-phase defineProvider in index.ts and curried defineOperation across sources.",
 		usage: "apifuse migrate-shape [path] [--check] [--json]",
 		examples: ["apifuse migrate-shape .", "apifuse migrate-shape . --check"],
 		modulePath: "./apifuse-migrate-shape",

package/src/cli/migrate-operation-shape.ts

@@ -0,0 +1,184 @@
+import type TS from "typescript";
+
+const ts: typeof import("typescript") = await loadTypeScript();
+
+async function loadTypeScript(): Promise<typeof import("typescript")> {
+	try {
+		return await import("typescript");
+	} catch {
+		console.error(
+			"apifuse migrate-shape requires typescript; install it in the workspace running the CLI (bun add -d typescript)",
+		);
+		process.exit(1);
+	}
+}
+
+/**
+ * Operation authoring-shape migration.
+ *
+ * `defineOperation` / `defineStreamOperation` changed alongside the provider
+ * builder in 2.2.0-beta.37: the identity helper became a curried,
+ * context-typed factory.
+ *
+ *   before: defineOperation({ ...config })
+ *   after:  defineOperation<ProviderContext>()({ ...config })
+ *
+ * The old call still type-checks against an older pin, but under the new SDK
+ * it returns the INNER FACTORY FUNCTION with the config swallowed as an
+ * ignored argument, so every operation in the map becomes a function and the
+ * provider fails `finalizeProvider` with a misleading "declares neither
+ * healthCheck nor healthCheckUnsupported" error. Measured fleet blast radius
+ * (2026-08-29): 53 of 84 repositories, 450 legacy call sites.
+ *
+ * Same contract as the provider-shape transform: rewrite only what is fully
+ * understood, report a reasoned skip otherwise, never emit a partial file.
+ */
+
+export type OperationShapeMigration =
+	| {
+			readonly status: "migrated";
+			readonly code: string;
+			/** Number of call sites rewritten in this file. */
+			readonly rewrites: number;
+			/** True when a `ProviderContext` type import was added. */
+			readonly importAdded: boolean;
+	  }
+	| { readonly status: "unchanged"; readonly code: string }
+	| { readonly status: "skipped"; readonly reason: string };
+
+const OPERATION_HELPERS = new Set(["defineOperation", "defineStreamOperation"]);
+const PROVIDER_CONTEXT_TYPE_NAME = "ProviderContext";
+const PROVIDER_SDK_PROVIDER_SUBPATH = "@apifuse/provider-sdk/provider";
+
+/**
+ * Migrate legacy `defineOperation(config)` calls in one source file to the
+ * curried `defineOperation<ProviderContext>()(config)` form.
+ *
+ * @param contextImportSpecifier module specifier the `ProviderContext` type
+ * import should come from when one has to be added — `"../index"` for
+ * operation modules, `"./index"` is never needed because index.ts declares
+ * the alias itself. Callers pass the correct relative path per file.
+ */
+export function migrateOperationShape(
+	sourceText: string,
+	fileName: string,
+	contextImportSpecifier: string,
+): OperationShapeMigration {
+	const source = ts.createSourceFile(
+		fileName,
+		sourceText,
+		ts.ScriptTarget.Latest,
+		true,
+		ts.ScriptKind.TS,
+	);
+
+	const parseError = firstSyntaxError(source);
+	if (parseError !== undefined) {
+		return { status: "skipped", reason: parseError };
+	}
+
+	// Every legacy call site: a direct call to the bare helper identifier
+	// whose single argument is the config (i.e. NOT the curried form, whose
+	// outer call has zero arguments and optional type arguments).
+	const legacyCalls: TS.CallExpression[] = [];
+	let sawCurried = false;
+	const visit = (node: TS.Node): void => {
+		if (
+			ts.isCallExpression(node) &&
+			ts.isIdentifier(node.expression) &&
+			OPERATION_HELPERS.has(node.expression.text)
+		) {
+			if (node.arguments.length === 0) {
+				sawCurried = true; // already-migrated outer call
+			} else {
+				legacyCalls.push(node);
+			}
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+
+	if (legacyCalls.length === 0) {
+		return { status: "unchanged", code: sourceText };
+	}
+
+	// A file mixing both forms almost certainly had a partial hand-migration;
+	// refuse rather than guess which convention the author wants.
+	if (sawCurried) {
+		return {
+			status: "skipped",
+			reason:
+				"File mixes legacy defineOperation(config) with curried defineOperation<...>()(config); migrate it by hand.",
+		};
+	}
+
+	const declaresContextAlias = source.statements.some(
+		(statement) =>
+			ts.isTypeAliasDeclaration(statement) &&
+			statement.name.text === PROVIDER_CONTEXT_TYPE_NAME,
+	);
+	const importsContext = sourceText.includes(PROVIDER_CONTEXT_TYPE_NAME);
+	const needsImport = !declaresContextAlias && !importsContext;
+
+	const edits: { start: number; end: number; text: string }[] = [];
+	for (const call of legacyCalls) {
+		// `defineOperation(` -> `defineOperation<ProviderContext>()(`
+		const callee = call.expression;
+		edits.push({
+			start: callee.getEnd(),
+			end: callee.getEnd(),
+			text: `<${PROVIDER_CONTEXT_TYPE_NAME}>()`,
+		});
+	}
+
+	let importAdded = false;
+	if (needsImport) {
+		const lastImport = [...source.statements]
+			.reverse()
+			.find((statement) => ts.isImportDeclaration(statement));
+		const insertAt = lastImport ? lastImport.getEnd() : 0;
+		const importText = `${lastImport ? "\n" : ""}import type { ${PROVIDER_CONTEXT_TYPE_NAME} } from "${contextImportSpecifier}";${lastImport ? "" : "\n"}`;
+		edits.push({ start: insertAt, end: insertAt, text: importText });
+		importAdded = true;
+	}
+
+	const ordered = edits.sort((a, b) => b.start - a.start);
+	let code = sourceText;
+	for (const edit of ordered) {
+		code = code.slice(0, edit.start) + edit.text + code.slice(edit.end);
+	}
+
+	const verified = ts.createSourceFile(
+		fileName,
+		code,
+		ts.ScriptTarget.Latest,
+		true,
+		ts.ScriptKind.TS,
+	);
+	const outputError = firstSyntaxError(verified);
+	if (outputError !== undefined) {
+		return {
+			status: "skipped",
+			reason: `Transform produced source that does not parse (${outputError}); refusing to emit a partial migration.`,
+		};
+	}
+
+	return {
+		status: "migrated",
+		code,
+		rewrites: legacyCalls.length,
+		importAdded,
+	};
+}
+
+function firstSyntaxError(source: TS.SourceFile): string | undefined {
+	const diagnostics = (
+		source as TS.SourceFile & { parseDiagnostics?: TS.DiagnosticWithLocation[] }
+	).parseDiagnostics;
+	if (diagnostics === undefined || diagnostics.length === 0) return undefined;
+	const first = diagnostics[0];
+	if (first === undefined) return undefined;
+	const message = ts.flattenDiagnosticMessageText(first.messageText, " ");
+	const { line } = source.getLineAndCharacterOfPosition(first.start);
+	return `${message} (line ${line + 1})`;
+}