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

package/bin/apifuse-check.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
@@ -11,8 +11,14 @@ import {
 	PROMPT_ASSET_SYNC_REMEDIATION,
 	verifyPromptAssets,
 } from "../src/cli/prompt-assets.js";
+import {
+	DECLARATION_INVALID_CODE,
+	validateFailClosedDeclaration,
+} from "../src/declaration-validation.js";
+import { redundantDeploymentDefaults } from "../src/cli/deployment-intent.js";
+import { isProviderError } from "../src/errors.js";
 import type { ProviderDefinition } from "../src/index.js";
-import { lintProvider, type ProviderLintMode } from "../src/lint.js";
+import { lintProviderWithInformation, type ProviderLintMode } from "../src/lint.js";
 import { safeParseSchemaSync } from "../src/schema.js";
 
 const HELP_TEXT = `Usage: apifuse check [path]
@@ -118,26 +124,84 @@ export async function runChecks(
 	const indexPath = resolve(providerRoot, "index.ts");
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
-
-	const providerModule = existsSync(indexPath)
-		? await import(pathToFileURL(indexPath).href)
-		: undefined;
+	const providerJsonPath = resolve(providerRoot, "provider.json");
+
+	let providerModule: Record<string, unknown> | undefined;
+	let providerImportError: unknown;
+	if (existsSync(indexPath)) {
+		try {
+			providerModule = (await import(pathToFileURL(indexPath).href)) as Record<string, unknown>;
+		} catch (error) {
+			if (isProviderError(error) && error.code === DECLARATION_INVALID_CODE) {
+				providerImportError = error;
+			} else {
+				throw error;
+			}
+		}
+	}
 	const provider = assertProviderDefinition(providerModule?.default);
 	const providerSourceFiles = collectProviderSourceFiles(providerRoot);
+	const localeCatalogEn = readEnglishLocaleCatalog(providerRoot);
 
 	return [
 		checkIndex(indexPath, provider),
+		checkDeclaration(provider, providerImportError),
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
-		checkAuthoringLint(provider, providerSourceFiles, options.lintMode),
+		checkAuthoringLint(provider, providerSourceFiles, localeCatalogEn, options.lintMode),
 		checkProviderMetadata(provider),
+		await checkDeploymentIntent(providerRoot, provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
+		checkProviderJson(providerJsonPath, packageJsonPath),
 		checkPromptAssets(providerRoot),
 	];
 }
 
+const DECLARATION_CHECK_MESSAGE = "Provider declaration passes fail-closed validation";
+
+function checkDeclaration(
+	provider: ProviderDefinition | undefined,
+	importError: unknown,
+): CheckResult {
+	if (importError !== undefined) {
+		return {
+			message: DECLARATION_CHECK_MESSAGE,
+			passed: false,
+			details: formatDeclarationError(importError),
+		};
+	}
+	if (!provider) return { message: DECLARATION_CHECK_MESSAGE, passed: false };
+	try {
+		validateFailClosedDeclaration(provider);
+		return { message: DECLARATION_CHECK_MESSAGE, passed: true };
+	} catch (error) {
+		return {
+			message: DECLARATION_CHECK_MESSAGE,
+			passed: false,
+			details: formatDeclarationError(error),
+		};
+	}
+}
+
+function formatDeclarationError(error: unknown): string[] {
+	if (isProviderError(error) && error.code === DECLARATION_INVALID_CODE) {
+		const details = error.details;
+		if (isRecord(details) && Array.isArray(details.violations)) {
+			return details.violations.map((violation) => {
+				if (!isRecord(violation)) return String(violation);
+				const ruleId = typeof violation.ruleId === "string" ? violation.ruleId : "unknown-rule";
+				const path = typeof violation.path === "string" ? violation.path : "unknown-path";
+				const message = typeof violation.message === "string" ? `: ${violation.message}` : "";
+				const fix = typeof violation.fix === "string" ? ` Fix: ${violation.fix}` : "";
+				return `${path} [${ruleId}]${message}${fix}`;
+			});
+		}
+	}
+	return [error instanceof Error ? error.message : String(error)];
+}
+
 export const PROMPT_ASSETS_CHECK_MESSAGE =
 	"Agent prompt assets match the installed SDK version";
 
@@ -162,6 +226,21 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+/**
+ * A directory under the provider root that is itself a git checkout — a linked
+ * worktree (`.worktree/<branch>/`, whose `.git` is a file pointing at the main
+ * repository), a nested clone (`.git` directory), or an initialised submodule.
+ * Its files are another revision of some repository, not this provider's
+ * runtime source: an older copy of `upstream/` or `scripts/` there would be
+ * linted as if it were request-path code at the root (the tooling-directory
+ * exemption is anchored at the provider root), and its `apifuse check` is run
+ * in that checkout, not here. Git refuses to track a path named `.git`, so the
+ * marker cannot be planted in a committed tree to hide a file from the scan.
+ */
+function isNestedCheckout(directory: string): boolean {
+	return existsSync(join(directory, ".git"));
+}
+
 function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
 	// `.agents`/`.apifuse` are deliberately not skipped: managed content there
@@ -172,7 +251,7 @@ function collectProviderSourceFiles(providerRoot: string): Record<string, string
 		for (const entry of readdirSync(directory, { withFileTypes: true })) {
 			const path = resolve(directory, entry.name);
 			if (entry.isDirectory()) {
-				if (!skipDirectories.has(entry.name)) {
+				if (!skipDirectories.has(entry.name) && !isNestedCheckout(path)) {
 					visit(path);
 				}
 				continue;
@@ -306,9 +385,30 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 	};
 }
 
+/**
+ * Reads `locales/en.json` so the error-localization lint rules can resolve
+ * declared `messageKey`/`fixKey` values. An absent or unreadable catalog is
+ * reported as an empty catalog rather than as "no catalog": a provider that
+ * references locale keys without shipping `en.json` must still fail the
+ * missing-key rule instead of silently skipping it.
+ */
+function readEnglishLocaleCatalog(providerRoot: string): Record<string, unknown> {
+	const catalogPath = resolve(providerRoot, "locales", "en.json");
+	if (!existsSync(catalogPath)) return {};
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(catalogPath, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+			? (parsed as Record<string, unknown>)
+			: {};
+	} catch {
+		return {};
+	}
+}
+
 function checkAuthoringLint(
 	provider: ProviderDefinition | undefined,
 	providerSourceFiles: Record<string, string>,
+	localeCatalogEn: Record<string, unknown>,
 	lintMode: ProviderLintMode = "official",
 ): CheckResult {
 	if (!provider) {
@@ -318,12 +418,21 @@ function checkAuthoringLint(
 		};
 	}
 
-	const diagnostics = lintProvider({ ...provider, providerSourceFiles }, { mode: lintMode });
+	const { diagnostics, information } = lintProviderWithInformation(
+		{ ...provider, providerSourceFiles, localeCatalogEn },
+		{ mode: lintMode },
+	);
 	const errors = diagnostics.filter((diagnostic) => diagnostic.level === "error");
-	const details = diagnostics.map((diagnostic) => {
-		const field = diagnostic.field ? `${diagnostic.field}: ` : "";
-		return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
+	const details = information.map((entry) => {
+		const field = entry.field ? `${entry.field}: ` : "";
+		return `INFO ${entry.rule} ${field}${entry.message}`;
 	});
+	details.push(
+		...diagnostics.map((diagnostic) => {
+			const field = diagnostic.field ? `${diagnostic.field}: ` : "";
+			return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
+		}),
+	);
 
 	return {
 		message: "Provider authoring lint has no error-level diagnostics",
@@ -378,6 +487,64 @@ function checkProviderMetadata(provider: ProviderDefinition | undefined): CheckR
 	};
 }
 
+export const DEPLOYMENT_INTENT_CHECK_MESSAGE =
+	"Deployment intent lives only in defineProvider({ deployment }) without restating profile defaults";
+export const LEGACY_DEPLOY_FILE_RULE = "deployment/legacy-deploy-file";
+export const REDUNDANT_DEPLOYMENT_DEFAULT_RULE = "deployment/redundant-default";
+export const SPREAD_EXPORT_DEPLOYMENT_RULE = "deployment/spread-export";
+
+/**
+ * Deployment intent has one authored home: the `deployment` key on
+ * `defineProvider()`, carrying only the fields that differ from the runtime
+ * profile. A standalone `deploy.ts` is a legacy surface and a field that
+ * restates a profile default is noise the platform derives anyway. Both are
+ * reported as warnings while the fleet migrates (`apifuse
+ * migrate-deployment`); they become errors once no repository carries the
+ * legacy file.
+ */
+async function checkDeploymentIntent(
+	providerRoot: string,
+	provider: ProviderDefinition | undefined,
+): Promise<CheckResult> {
+	const details: string[] = [];
+	if (existsSync(resolve(providerRoot, "deploy.ts"))) {
+		details.push(
+			`WARN ${LEGACY_DEPLOY_FILE_RULE}: deploy.ts is a legacy deployment surface; run \`apifuse migrate-deployment .\` to move its non-default values into defineProvider({ deployment }) and delete the file.`,
+		);
+	}
+	// A `deployment` extra on `export default { ...provider, deployment }` is
+	// indistinguishable from a declaration key once the module is loaded, so
+	// inspect the source. The inspector needs the TypeScript compiler (a
+	// devDependency of provider repositories); without it this rule is skipped.
+	const indexPath = resolve(providerRoot, "index.ts");
+	if (existsSync(indexPath)) {
+		try {
+			const { findSpreadExportDeploymentProperty } = await import(
+				"../src/cli/migrate-deployment-intent.js"
+			);
+			const spread = findSpreadExportDeploymentProperty(readFileSync(indexPath, "utf8"), indexPath);
+			if (spread !== undefined) {
+				details.push(
+					`WARN ${SPREAD_EXPORT_DEPLOYMENT_RULE}: index.ts:${spread.line} attaches \`deployment\` to a spread default export; the only authored surface is the \`deployment\` key inside defineProvider({...}). Run \`apifuse migrate-deployment .\` to hoist it.`,
+				);
+			}
+		} catch {
+			// TypeScript unavailable: the source-shape rule cannot run here.
+		}
+	}
+	if (provider?.deployment !== undefined) {
+		for (const redundant of redundantDeploymentDefaults(provider.deployment)) {
+			details.push(`WARN ${REDUNDANT_DEPLOYMENT_DEFAULT_RULE}: ${redundant.message}`);
+		}
+	}
+	return {
+		message: DEPLOYMENT_INTENT_CHECK_MESSAGE,
+		// Warning-only during the fleet migration window.
+		passed: true,
+		details,
+	};
+}
+
 function checkDockerfile(dockerfilePath: string): CheckResult {
 	return {
 		message: "Dockerfile exists",
@@ -419,6 +586,119 @@ function checkPackageJson(packageJsonPath: string): CheckResult {
 	}
 }
 
+export const PROVIDER_JSON_CHECK_MESSAGE = "provider.json exists with a valid declaration";
+
+/**
+ * Markets a provider may declare as its primary, and the locales the platform
+ * catalogs can carry.
+ *
+ * These mirror `scripts/provider-deploy/provider-locale-coverage.mjs` in the
+ * APIFuse monorepo, which is the policy's source of truth. The duplication is
+ * deliberate and bounded: the monorepo cannot be imported from a provider
+ * checkout, and a *closed* mirror is the point — it keeps a typo
+ * (`primaryMarket: "jp-JP"`) a local failure instead of one that only surfaces
+ * in the monorepo's contract validator days later.
+ */
+const PROVIDER_PRIMARY_MARKETS = ["jp", "kr", "global"] as const;
+const PROVIDER_COVERAGE_LOCALES = ["en", "ko", "ja"] as const;
+const PROVIDER_BASELINE_LOCALE = "en";
+
+/**
+ * Declared locale coverage, optional at schemaVersion 1.
+ *
+ * `apifuse provider declare-locale-coverage` writes this block, and the
+ * monorepo declaration schema has accepted it since the rollout landed. This
+ * check used to close `provider.json` over four keys, which made the only
+ * documented way to clear the monorepo's `LOCALE_COVERAGE_UNDECLARED` finding
+ * turn a green `bun run check` red — the declaration was unfixable from either
+ * side. The fix is to mirror the monorepo schema rather than to stop
+ * validating: the block stays closed over its own two keys so a misspelled
+ * field is still caught here, at authoring time.
+ */
+const providerI18nDeclarationSchema = z
+	.object({
+		primaryMarket: z.enum(PROVIDER_PRIMARY_MARKETS),
+		locales: z
+			.array(z.enum(PROVIDER_COVERAGE_LOCALES))
+			.nonempty()
+			.refine((locales) => new Set(locales).size === locales.length, {
+				message: "i18n.locales must not repeat a locale",
+			})
+			.refine((locales) => locales.includes(PROVIDER_BASELINE_LOCALE), {
+				message: `i18n.locales must include "${PROVIDER_BASELINE_LOCALE}": it is the fallback every other locale resolves through`,
+			})
+			.optional(),
+	})
+	.strict();
+
+const providerDeclarationSchema = z
+	.object({
+		schemaVersion: z.literal(1),
+		providerId: z.string(),
+		owner: z.string(),
+		lifecycle: z.enum(["draft", "ready", "live", "retired"]),
+		i18n: providerI18nDeclarationSchema.optional(),
+	})
+	.strict();
+
+function checkProviderJson(providerJsonPath: string, packageJsonPath: string): CheckResult {
+	if (!existsSync(providerJsonPath)) {
+		return {
+			message: PROVIDER_JSON_CHECK_MESSAGE,
+			passed: false,
+			details: ["Missing provider.json at the provider root"],
+		};
+	}
+
+	try {
+		const declaration = providerDeclarationSchema.parse(
+			JSON.parse(readFileSync(providerJsonPath, "utf-8")) as unknown,
+		);
+		const expectedProviderId = readProviderIdFromPackageName(packageJsonPath);
+		if (expectedProviderId !== undefined && declaration.providerId !== expectedProviderId) {
+			return {
+				message: PROVIDER_JSON_CHECK_MESSAGE,
+				passed: false,
+				details: [
+					`provider.json providerId "${declaration.providerId}" does not match package.json name (expected "${expectedProviderId}")`,
+				],
+			};
+		}
+
+		return {
+			message: PROVIDER_JSON_CHECK_MESSAGE,
+			passed: true,
+			details: [
+				`providerId: ${declaration.providerId}`,
+				`lifecycle: ${declaration.lifecycle}`,
+				...(declaration.i18n
+					? [
+							`locale coverage: primaryMarket ${declaration.i18n.primaryMarket}${
+								declaration.i18n.locales ? ` (locales: ${declaration.i18n.locales.join(", ")})` : ""
+							}`,
+						]
+					: []),
+			],
+		};
+	} catch (error) {
+		return {
+			message: PROVIDER_JSON_CHECK_MESSAGE,
+			passed: false,
+			details: [error instanceof Error ? error.message : String(error)],
+		};
+	}
+}
+
+function readProviderIdFromPackageName(packageJsonPath: string): string | undefined {
+	try {
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as unknown;
+		if (!isRecord(packageJson) || typeof packageJson.name !== "string") return undefined;
+		return /^(?:apifuse-provider-|@apifuse\/provider-)(.+)$/.exec(packageJson.name)?.[1];
+	} catch {
+		return undefined;
+	}
+}
+
 function assertProviderDefinition(value: unknown): ProviderDefinition | undefined {
 	return isProviderDefinition(value) ? value : undefined;
 }
@@ -431,7 +711,7 @@ function isProviderDefinition(value: unknown): value is ProviderDefinition {
 	return (
 		typeof value.id === "string" &&
 		typeof value.version === "string" &&
-		(value.runtime === "standard" || value.runtime === "browser") &&
+		(value.runtime === "standard" || value.runtime === "shared" || value.runtime === "browser") &&
 		typeof value.meta.displayName === "string" &&
 		typeof value.meta.category === "string"
 	);

package/bin/apifuse-dev.ts

@@ -1,21 +1,27 @@
 #!/usr/bin/env bun
+import { readDiagnosticEnv } from "../src/runtime/diagnostic-env.js";
 
 import { existsSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import type { ProviderDefinition } from "../src/index.js";
 import {
-	createBrowserClient,
 	createCredentialContext,
-	createEnvContext,
 	createHttpClient,
+	createInProcessProviderEngine,
+	createOcrClientFromEnv,
 	createProviderCache,
-	createProviderChoiceContext,
-	createStealthClient,
+	createHandleContext,
+	createProviderEnvironment,
 	createSttClientFromEnv,
-	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	type ProviderDefinition,
+	type ProviderEngineBindingCandidates,
 	ProviderError,
 } from "../src/index.js";
+import { createCliResolverRuntime } from "../src/cli/resolver-runtime.js";
+import { assertProcessEngineModeSupported } from "../src/runtime/engine-mode.js";
+import { createBrowserClient } from "../src/runtime/browser.js";
 import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
+import { createStealthClient } from "../src/runtime/stealth.js";
+import type { ResolverTelemetryCollector } from "../src/runtime/resolver-telemetry.js";
 import { createTraceContext } from "../src/runtime/trace.js";
 import type { BrowserClient, ProviderContext } from "../src/types.js";
 
@@ -35,6 +41,9 @@ export async function main() {
 	const providerModule = await import(resolve(providerPath, "index.ts"));
 	const provider = assertProviderDefinition(providerModule.default, providerPath);
 
+	// Fail fast before the server starts: this is a developer tool, and an
+	// explicit remote request must never silently fall back to in-process.
+	assertProcessEngineModeSupported();
 	const { startDevServer } = await import("../src/dev.js");
 	const port = Number(process.env.APIFUSE__RUNTIME__PORT) || 3900;
 
@@ -42,6 +51,7 @@ export async function main() {
 
 	console.log("\nEndpoints:");
 	console.log(`  GET  http://localhost:${port}/health`);
+	console.log(`  GET  http://localhost:${port}/readyz`);
 
 	for (const operationId of Object.keys(provider.operations)) {
 		console.log(`  POST http://localhost:${port}/v1/${operationId}`);
@@ -73,15 +83,19 @@ export async function main() {
 
 export function createProviderContext(provider: ProviderDefinition): {
 	ctx: ProviderContext;
+	resolverTelemetry: ResolverTelemetryCollector;
 } {
-	const env = createEnvContext([
-		...(provider.secrets?.map((secret) => secret.name) ?? []),
-		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-	]);
+	const providerEnvironment = createProviderEnvironment(
+		process.env,
+		provider.secrets?.map((secret) => secret.name) ?? [],
+	);
+	const providerEnv = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
 	const credential = createCredentialContext();
 	const state = createMemoryProviderRuntimeState();
-	const ctx: ProviderContext = {
-		env,
+	const cache = createProviderCache({ providerId: provider.id });
+	const { resolver, resolverTelemetry } = createCliResolverRuntime(provider, cache);
+	const candidates: ProviderEngineBindingCandidates = {
+		env: providerEnv,
 		credential,
 		auth: createUnsupportedAuthStub(),
 		browser:
@@ -92,20 +106,29 @@ export function createProviderContext(provider: ProviderDefinition): {
 					})
 				: createUnsupportedBrowserStub(),
 		http: createHttpClient(),
-		cache: createProviderCache({ providerId: provider.id }),
+		cache,
 		state,
 		trace: createTraceContext(),
-		stealth: createStealthClient("http://localhost"),
+		stealth: createStealthClient("http://localhost", {
+			...(provider.stealth ? { stealth: provider.stealth } : {}),
+		}),
+		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
-		choice: createProviderChoiceContext({
+		resolver,
+		handle: createHandleContext({
 			providerId: provider.id,
-			env,
-			credential,
+			// Local dev is a single-user session: one stable connection scope so
+			// bound handles (drafts, default cursors) work exactly as in production.
+			request: { headers: {}, connectionId: "local-dev" },
 			state,
 		}),
 	};
+	const ctx = createInProcessProviderEngine().attach({
+		provider,
+		bindings: candidates,
+	}) as ProviderContext;
 
-	return { ctx };
+	return { ctx, resolverTelemetry };
 }
 
 function normalizeArgs(argv: string[]): string[] {
@@ -216,7 +239,7 @@ function isProviderDefinition(value: unknown): value is ProviderDefinition {
 	return (
 		typeof value.id === "string" &&
 		typeof value.version === "string" &&
-		(value.runtime === "standard" || value.runtime === "browser") &&
+		(value.runtime === "standard" || value.runtime === "shared" || value.runtime === "browser") &&
 		typeof value.meta.displayName === "string" &&
 		typeof value.meta.category === "string"
 	);