@apifuse/provider-sdk 2.2.0-beta.62 → 2.2.0-beta.64

package/bin/apifuse-record.ts

@@ -14,7 +14,6 @@ import {
 	createHandleContext,
 	createProviderEnvironment,
 	createSttClientFromEnv,
-	createUnsupportedResolverClient,
 	executeOperation,
 	type HttpClient,
 	type HttpResponse,
@@ -23,13 +22,13 @@ import {
 	type ProviderDefinition,
 	type ProviderEngineBindingCandidates,
 	ProviderError,
-	readEngineProxyCredentials,
-	type ProviderProxyPolicy,
 	type RequestOptions,
 	type StealthClient,
 	TransportError,
 	ValidationError,
 } from "../src/index.js";
+import { createCliResolverRuntime } from "../src/cli/resolver-runtime.js";
+import { assertProcessEngineModeSupported } from "../src/runtime/engine-mode.js";
 import type { JsonValue } from "../src/contract-json.js";
 import {
 	isSensitiveFixtureKey,
@@ -37,7 +36,6 @@ import {
 	sanitizeDiagnosticText,
 	sanitizeFixtureString,
 } from "../src/fixture-sanitization.js";
-import { createResolverClientFromEnv } from "../src/runtime/resolver.js";
 import {
 	isSensitiveKey,
 	normalizeSensitiveParams,
@@ -50,10 +48,10 @@ import {
 	requestOptionsFromHttpInvocation,
 	serializeRequestUrl,
 } from "../src/runtime/request-options.js";
+import type { ResolverTelemetryCollector } from "../src/runtime/resolver-telemetry.js";
 import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
 import { createStealthClient } from "../src/runtime/stealth.js";
 import { parseSchema } from "../src/schema.js";
-import { getStealthProfile } from "../src/stealth/profiles.js";
 import {
 	captureStreamEvidence,
 	createStreamCaptureEnvelope,
@@ -107,6 +105,8 @@ export async function main() {
 		const args = parseArgs(normalizeArgs(process.argv.slice(2)));
 		const location = resolveProviderLocation(args.providerPath);
 		const provider = await loadProvider(location.rootDir);
+		// The capture context attaches in-process; refuse an explicit remote request instead of ignoring it.
+		assertProcessEngineModeSupported();
 		const operationName = resolveOperationName(provider, args.operation);
 		const operation = provider.operations[operationName];
 		const parsedParams = await parseParams(operation, args.params);
@@ -140,6 +140,12 @@ export async function main() {
 				);
 			}
 			throw operationError;
+		} finally {
+			const telemetryLine = formatResolverTelemetry(
+				capture.resolverTelemetry,
+				capture.getCapturedSensitiveParams().values,
+			);
+			if (telemetryLine) console.log(telemetryLine);
 		}
 		const captured = await capture.getCapturedRaw();
 
@@ -256,6 +262,25 @@ function parseArgs(argv: string[]): CliArgs {
 	return { append, providerPath, operation, params, sanitize };
 }
 
+/**
+ * The `resolver` sibling of the server request log, printed once per recorded invocation. The
+ * collector redacts at record time with the values registered so far; the mandatory query-secret
+ * pass over the final line also covers values captured after a solve and short low-entropy values
+ * the diagnostic redactor does not match, the same way handleCliError treats CLI errors.
+ */
+export function formatResolverTelemetry(
+	collector: ResolverTelemetryCollector,
+	sensitiveValues: readonly string[] = [],
+): string | undefined {
+	const resolver = collector.toLogPayload();
+	return resolver
+		? `[apifuse record] Resolver telemetry ${redactSensitiveText(
+				JSON.stringify({ resolver }),
+				sensitiveValues,
+			)}`
+		: undefined;
+}
+
 function handleCliError(error: unknown, sensitiveValues: readonly string[] = []): never {
 	const message = redactSensitiveText(formatCliError(error), sensitiveValues);
 	console.error(`[apifuse record] ${message}`);
@@ -430,13 +455,6 @@ function resolveOperationBaseUrl(provider: ProviderRuntime, operationName: strin
 	return baseUrl;
 }
 
-function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPolicy | undefined {
-	if (typeof provider.proxy === "object") return provider.proxy;
-	if (provider.proxy === true) return { mode: "optional" };
-	if (provider.proxy === false) return { mode: "disabled" };
-	return undefined;
-}
-
 export function createCaptureContext(
 	provider: ProviderRuntime,
 	baseUrl: string,
@@ -454,8 +472,19 @@ export function createCaptureContext(
 	let capturedSse: { order: number; method: string; path: string } | undefined;
 	const sensitiveParamNames = new Set<string>();
 	const sensitiveParamValues = new Set<string>();
+	const cache = createBypassProviderCache({ providerId: provider.id });
+	const { resolver, resolverTelemetry, registerSensitiveValues } = createCliResolverRuntime(
+		provider,
+		cache,
+	);
 	const captureSensitiveParams = (url: string, options?: SensitiveRequestOptions) => {
-		captureSensitiveRequestValues(url, options, sensitiveParamNames, sensitiveParamValues);
+		try {
+			captureSensitiveRequestValues(url, options, sensitiveParamNames, sensitiveParamValues);
+		} finally {
+			// Resolver telemetry redacts at record time, so the vendor diagnostics of a later solve
+			// must not echo a query secret captured here (same guarantee as handleCliError).
+			registerSensitiveValues([...sensitiveParamValues]);
+		}
 	};
 	const getCapturedSensitiveParams = (): CapturedSensitiveParams => ({
 		names: [...sensitiveParamNames],
@@ -521,7 +550,6 @@ export function createCaptureContext(
 		provider.secrets?.map((secret) => secret.name) ?? [],
 	);
 	const env = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
-	const engineCredentials = readEngineProxyCredentials();
 	const credential = {
 		mode: "none" as const,
 		get: () => undefined,
@@ -530,9 +558,6 @@ export function createCaptureContext(
 		getScopes: () => [],
 	};
 	const state = createMemoryProviderRuntimeState();
-	const cache = createBypassProviderCache({ providerId: provider.id });
-	const proxyPolicy = resolveNativeProxyPolicy(provider);
-	const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
 	const candidates: ProviderEngineBindingCandidates = {
 		env,
 		credential,
@@ -567,21 +592,7 @@ export function createCaptureContext(
 		},
 		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
-		resolver: provider.resolver
-			? createResolverClientFromEnv(provider.resolver, engineCredentials, {
-					allowedHosts: provider.allowedHosts,
-					cache,
-					...(proxyPolicy
-						? {
-								proxyIntent: {
-									mode: proxyPolicy.mode,
-									upstream: { proxy: provider.proxy },
-									...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
-								},
-							}
-						: {}),
-				})
-			: createUnsupportedResolverClient("Provider does not declare resolver capability"),
+		resolver,
 		handle: createHandleContext({
 			providerId: provider.id,
 			request: { headers: {}, connectionId: "local-record" },
@@ -595,6 +606,7 @@ export function createCaptureContext(
 
 	return {
 		ctx,
+		resolverTelemetry,
 		getCapturedRaw: async () => {
 			if (streamCaptures.length === 0) {
 				if (capturedSse) throw unsupportedSseCaptureError(capturedSse);

package/bin/apifuse-submit-check.ts

@@ -25,18 +25,22 @@ import {
 	hasStreamEvidenceMarker,
 	parseStreamEvidenceRecord,
 } from "../src/stream-evidence.js";
+import { getTypeScript } from "../src/typescript-module.js";
 import { type CheckResult, PROMPT_ASSETS_CHECK_MESSAGE, runChecks } from "./apifuse-check.js";
 import { hasSubstantiveDelimitedTextStructure } from "./submit-check-delimited-text.js";
 import { hasSubstantiveXmlStructure } from "./submit-check-xml.js";
 
-const ts: typeof import("typescript") = await loadTypeScript();
+const ts: typeof import("typescript") = loadTypeScript();
 
-async function loadTypeScript(): Promise<typeof import("typescript")> {
+// Shares the lint rules' loader so a workspace whose `typescript` is the 7.x
+// native shell (no compiler API) falls back to `@typescript/typescript6`
+// instead of failing inside the first parse.
+function loadTypeScript(): typeof import("typescript") {
 	try {
-		return await import("typescript");
-	} catch {
+		return getTypeScript();
+	} catch (error) {
 		console.error(
-			"apifuse submit-check requires typescript; install it in the workspace running the CLI (bun add -d typescript)",
+			`apifuse submit-check requires the TypeScript compiler API; install it in the workspace running the CLI (bun add -d typescript). ${error instanceof Error ? error.message : String(error)}`,
 		);
 		process.exit(1);
 	}

package/bin/apifuse-test.ts

@@ -687,4 +687,6 @@ function extractLastMatch(
 	return matches[matches.length - 1];
 }
 
-void main();
+if (import.meta.main) {
+	await main();
+}

package/dist/cli/commands.d.ts

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

package/dist/cli/commands.js

@@ -47,6 +47,16 @@ export const COMMAND_MANIFEST = {
         ],
         modulePath: "./apifuse-migrate-operation-declaration",
     },
+    "migrate-deployment": {
+        name: "migrate-deployment",
+        summary: "Retire a legacy deploy.ts: hoist its non-default values into the defineProvider() deployment key and delete the file.",
+        usage: "apifuse migrate-deployment [path] [--check] [--json] [--drop-codeowners-lock]",
+        examples: [
+            "apifuse migrate-deployment .",
+            "apifuse migrate-deployment . --check --json",
+        ],
+        modulePath: "./apifuse-migrate-deployment",
+    },
     "submit-check": {
         name: "submit-check",
         summary: "Score provider bounty submission readiness and emit checklist evidence.",
@@ -100,6 +110,7 @@ export const COMMAND_ORDER = [
     "sync-assets",
     "migrate-shape",
     "migrate-operation-declaration",
+    "migrate-deployment",
     "submit-check",
     "record",
     "test",

package/dist/cli/deployment-intent.d.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import type { ProviderDeploymentOverrides } from "../types.js";
+/**
+ * Deployment-intent helpers shared by `apifuse check` and
+ * `apifuse migrate-deployment`.
+ *
+ * Deployment intent has exactly one authored home: the optional `deployment`
+ * key on `defineProvider()`. The APIFuse registry builder is the only reader;
+ * it resolves omitted fields from a runtime profile and rejects anything it
+ * cannot resolve. This module mirrors that profile table so the CLI can
+ * (a) subtract profile defaults when hoisting a legacy `deploy.ts` into the
+ * key and (b) warn when a declared key restates a default. The registry
+ * stays canonical — keep the constants below identical to
+ * `resolveProviderDeploymentConfig` in `@apifuse/provider-registry`.
+ */
+export type DeploymentRuntime = "shared" | "dedicated" | "browser";
+export type DeploymentLanguage = "typescript" | "python";
+export interface DeploymentResources {
+    cpu: string;
+    memory: string;
+}
+export interface DeploymentHpa {
+    enabled: boolean;
+    minReplicas?: number;
+    maxReplicas?: number;
+    targetCPUUtilizationPercentage?: number;
+}
+/** Fully resolved deployment view: what the platform materializes for a provider. */
+export interface ResolvedDeploymentIntent {
+    runtime: DeploymentRuntime;
+    language: DeploymentLanguage;
+    replicas: number;
+    hpa: DeploymentHpa;
+    resources: DeploymentResources;
+    cache?: {
+        redis?: {
+            enabled: boolean;
+            url?: string;
+        };
+    };
+    network?: {
+        additionalTcpPorts: number[];
+    };
+    buildContext: string;
+}
+/**
+ * Runtime-profile defaults. `dedicated` carries no resource profile and
+ * therefore always needs explicit `resources`.
+ */
+export declare const DEPLOYMENT_PROFILE_DEFAULTS: Readonly<{
+    runtime: DeploymentRuntime;
+    language: DeploymentLanguage;
+    replicas: 1;
+    hpa: Readonly<DeploymentHpa>;
+    buildContext: ".";
+    resources: Readonly<Record<DeploymentRuntime, Readonly<DeploymentResources> | undefined>>;
+}>;
+/**
+ * The standalone `deploy.ts` contract (legacy). Mirrors the registry's
+ * `ProviderDeploymentConfigSchema`, including its own defaults — note that a
+ * legacy file without `hpa` resolved to `{ enabled: false }`, not the
+ * profile HPA, so the two default tables are deliberately different.
+ */
+export declare const legacyDeploymentConfigSchema: z.ZodObject<{
+    runtime: z.ZodEnum<{
+        browser: "browser";
+        shared: "shared";
+        dedicated: "dedicated";
+    }>;
+    language: z.ZodEnum<{
+        typescript: "typescript";
+        python: "python";
+    }>;
+    replicas: z.ZodDefault<z.ZodNumber>;
+    hpa: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        minReplicas: z.ZodOptional<z.ZodNumber>;
+        maxReplicas: z.ZodOptional<z.ZodNumber>;
+        targetCPUUtilizationPercentage: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    resources: z.ZodObject<{
+        cpu: z.ZodString;
+        memory: z.ZodString;
+    }, z.core.$strict>;
+    cache: z.ZodOptional<z.ZodObject<{
+        redis: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    network: z.ZodOptional<z.ZodObject<{
+        additionalTcpPorts: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    buildContext: z.ZodOptional<z.ZodString & z.ZodType<".", string, z.core.$ZodTypeInternals<".", string>>>;
+}, z.core.$strict>;
+/** The authored `deployment` key: every field optional (registry `ProviderDeploymentOverridesSchema`). */
+export declare const deploymentOverridesSchema: z.ZodObject<{
+    runtime: z.ZodOptional<z.ZodEnum<{
+        browser: "browser";
+        shared: "shared";
+        dedicated: "dedicated";
+    }>>;
+    language: z.ZodOptional<z.ZodEnum<{
+        typescript: "typescript";
+        python: "python";
+    }>>;
+    replicas: z.ZodOptional<z.ZodNumber>;
+    hpa: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        minReplicas: z.ZodOptional<z.ZodNumber>;
+        maxReplicas: z.ZodOptional<z.ZodNumber>;
+        targetCPUUtilizationPercentage: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    resources: z.ZodOptional<z.ZodObject<{
+        cpu: z.ZodString;
+        memory: z.ZodString;
+    }, z.core.$strict>>;
+    cache: z.ZodOptional<z.ZodObject<{
+        redis: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    network: z.ZodOptional<z.ZodObject<{
+        additionalTcpPorts: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    buildContext: z.ZodOptional<z.ZodString & z.ZodType<".", string, z.core.$ZodTypeInternals<".", string>>>;
+}, z.core.$strict>;
+export type DeploymentParse<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Parse a legacy `deploy.ts` default export into the resolved view. */
+export declare function normalizeLegacyDeployment(value: unknown): DeploymentParse<ResolvedDeploymentIntent>;
+/** Parse an authored `deployment` key against the strict overrides contract. */
+export declare function parseDeploymentIntent(value: unknown): DeploymentParse<ProviderDeploymentOverrides>;
+/**
+ * Resolve an authored key against the runtime profiles, per field;
+ * `resources` and `hpa` resolve as whole objects (never deep-merged).
+ * Throws when the intent cannot resolve (dedicated runtime without
+ * resources, non-default buildContext) — the registry rejects the same.
+ */
+export declare function resolveDeploymentIntent(intent?: ProviderDeploymentOverrides): ResolvedDeploymentIntent;
+/**
+ * Two resolved views describe the same deployment when they are deep-equal
+ * after dropping empty shells (`network: { additionalTcpPorts: [] }`,
+ * `cache: {}`) that carry no intent — the manifests they render are
+ * byte-identical.
+ */
+export declare function deploymentIntentsEquivalent(left: ResolvedDeploymentIntent, right: ResolvedDeploymentIntent): boolean;
+export declare function canonicalResolvedDeployment(resolved: ResolvedDeploymentIntent): ResolvedDeploymentIntent;
+/**
+ * The smallest `deployment` key that resolves to `resolved`: profile
+ * defaults are omitted, `hpa`/`resources` are kept whole when they differ
+ * (the resolver never deep-merges them), and empty shells are dropped.
+ * Callers prove the result with
+ * `deploymentIntentsEquivalent(resolveDeploymentIntent(key), resolved)`.
+ */
+export declare function subtractDeploymentDefaults(resolved: ResolvedDeploymentIntent): ProviderDeploymentOverrides;
+/** Authored order for emitted keys: the registry contract's field order. */
+export declare const DEPLOYMENT_INTENT_FIELD_ORDER: readonly (keyof ProviderDeploymentOverrides)[];
+export interface RedundantDeploymentField {
+    /** Dotted path under `deployment`, e.g. `hpa` or `network.additionalTcpPorts`. */
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Fields of an authored `deployment` key that restate what the runtime
+ * profile already resolves (ADR-0009 "derived values are not re-stated").
+ * Accepts an unvalidated value because `apifuse check` inspects the loaded
+ * definition, whose key the SDK passes through verbatim.
+ */
+export declare function redundantDeploymentDefaults(intent: unknown): RedundantDeploymentField[];
+/** Structural equality for JSON-shaped values, key order insensitive. */
+export declare function deepEqual(left: unknown, right: unknown): boolean;