@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.51

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-imported-array-spread.ts.txt

@@ -0,0 +1,9 @@
+import { LIST_INPUT_EXAMPLES } from "./shared.js";
+
+const importedExamplesOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [...LIST_INPUT_EXAMPLES],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-map.ts.txt

@@ -0,0 +1,5 @@
+import { searchOperation } from "./search";
+
+export const operations = {
+	search: searchOperation,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-mixed-array-spread.ts.txt

@@ -0,0 +1,24 @@
+const SHARED_INPUT_EXAMPLES = [
+	{
+		scenario: "Shared middle example",
+		input: { page: 2 },
+	},
+] as const;
+
+const mixedOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [
+		{
+			scenario: "Literal first example",
+			input: { page: 1 },
+		},
+		...SHARED_INPUT_EXAMPLES,
+		{
+			scenario: "Literal last example",
+			input: { page: 3 },
+		},
+	],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-operation.ts.txt

@@ -0,0 +1,16 @@
+export const searchOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [
+		{
+			scenario: "Search by a precise phrase",
+			input: {
+				query: `京都
+  ホテル`,
+			},
+			rationale: "Shows whitespace preservation",
+		},
+	],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-map.ts.txt

@@ -0,0 +1,3 @@
+export default buildProvider({
+	operations: createTabelogProvider(client),
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/hoist-all.ts.txt

@@ -0,0 +1,31 @@
+const searchOperation = defineOperation<ProviderContext>()({
+	annotations: {
+		readOnly: true,
+		openWorld: true,
+		idempotent: true,
+		rateLimit: { requests: 10 },
+		timeoutMs: 30_000,
+	},
+	toolRouter: {
+		name: "ignored",
+		requiresConnection: false,
+		connectionExternalRefParam: "accountId",
+	},
+	docs: {
+		titleKey: "operations.search.title",
+		descriptionKey: "operations.search.description",
+		summaryKey: "operations.search.summary",
+		markdownKey: "operations.search.markdown",
+		normalizationNotesKeys: ["operations.search.normalization.one"],
+		errorCodes: [{ code: "UPSTREAM" }],
+		requestExample: { query: "old" },
+		responseExample: { items: [] },
+	},
+	derivations: { value: "unused" } as unknown as Derivations,
+	retryOnAuthRefresh: true as unknown as boolean,
+	title: "Raw title" as unknown as string,
+	description: "Raw description" as unknown as string,
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/hoisted-const.ts.txt

@@ -0,0 +1,11 @@
+const annotations = {
+	readOnly: true,
+	timeoutMs: 15_000,
+} as const;
+
+const detailOperation = defineOperation<ProviderContext>()({
+	annotations,
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/imported-spread.ts.txt

@@ -0,0 +1,11 @@
+import { toolRouterDefaults } from "./tool-router-defaults.js";
+
+const importedSpreadOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	toolRouter: {
+		...toolRouterDefaults,
+	},
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/inline-map.ts.txt

@@ -0,0 +1,11 @@
+const provider = buildProvider({
+	operations: {
+		ping: {
+			annotations: { readOnly: true },
+			docs: { descriptionKey: "operations.ping.description" },
+			input: InputSchema,
+			output: OutputSchema,
+			handler,
+		},
+	},
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/inline-spread-cast-tail.ts.txt

@@ -0,0 +1,21 @@
+const castTailOperation = defineOperation<ProviderContext>()({
+	annotations: {
+		...({ timeoutMs: 15_000 as Milliseconds } as unknown as LegacyAnnotations),
+	},
+	toolRouter: {
+		...({
+			riskClass: "write" as const,
+			approval: "always" as ApprovalMode,
+			connectionMode: "none" as ConnectionMode,
+		} as unknown as LegacyToolRouter),
+	},
+	docs: {
+		...({
+			titleKey: "operations.castTail.title" as const,
+			descriptionKey: "operations.castTail.description" as LocaleKey,
+		} as unknown as LegacyDocs),
+	},
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/inline-spread-ekitan.ts.txt

@@ -0,0 +1,11 @@
+const getStationInfoOperation = defineOperation<ProviderContext>()({
+	toolRouter: {
+		riskClass: "read",
+		approval: "never",
+		requiresConnection: false,
+		...{ connectionMode: "none" as const },
+	},
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/inline-spread-override.ts.txt

@@ -0,0 +1,14 @@
+const overrideOperation = defineOperation<ProviderContext>()({
+	toolRouter: {
+		riskClass: "read",
+		connectionMode: "required" as const,
+		...{
+			connectionMode: "none" as const,
+			approval: "never" as const,
+		},
+		approval: "always" as const,
+	},
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/missing-english-locale.ts.txt

@@ -0,0 +1,7 @@
+const searchOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Search by title", input: { query: "castle" } }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/no-safety.ts.txt

@@ -0,0 +1,6 @@
+const unknownOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: false, destructive: false },
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/non-literal.ts.txt

@@ -0,0 +1,7 @@
+const READ_ONLY = true;
+const searchOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: READ_ONLY },
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/redundant-approval.ts.txt

@@ -0,0 +1,6 @@
+const searchOperation = defineOperation<ProviderContext>()({
+	toolRouter: { riskClass: "read", approval: "never" },
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/safety-conflict.ts.txt

@@ -0,0 +1,7 @@
+const cancelOperation = defineOperation<ProviderContext>()({
+	annotations: { destructive: true },
+	toolRouter: { riskClass: "write" },
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/stream.ts.txt

@@ -0,0 +1,7 @@
+const downloadOperation = defineStreamOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	toolRouter: { connectionMode: "optional" },
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/tool-router-spread.ts.txt

@@ -0,0 +1,15 @@
+const requiredConnection = {
+	requiresConnection: true,
+	connectionExternalRefParam: "profileId",
+} as const;
+
+const updateOperation = defineOperation<ProviderContext>()({
+	annotations: { destructive: true },
+	toolRouter: {
+		...requiredConnection,
+		approval: "always",
+	},
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/unparseable.ts.txt

@@ -0,0 +1,4 @@
+const brokenOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	input:,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/verbatim-template.ts.txt

@@ -0,0 +1,12 @@
+const explainOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	docs: { descriptionKey: "operations.explain.description" },
+	input: InputSchema,
+	output: OutputSchema,
+	handler: async () => {
+		const message = `最初の行
+  ${value}
+	最後の行`;
+		return { message };
+	},
+});

package/src/cli/commands.ts

@@ -2,6 +2,9 @@ export type ApifuseCommandName =
 	| "create"
 	| "dev"
 	| "check"
+	| "sync-assets"
+	| "migrate-shape"
+	| "migrate-operation-declaration"
 	| "submit-check"
 	| "bounty-check"
 	| "record"
@@ -46,6 +49,33 @@ 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",
+	},
+	"migrate-shape": {
+		name: "migrate-shape",
+		summary:
+			"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",
+	},
+	"migrate-operation-declaration": {
+		name: "migrate-operation-declaration",
+		summary:
+			"Migrate legacy nested operation declarations to the ADR-0009 flat shape, refusing ambiguous safety or metadata.",
+		usage: "apifuse migrate-operation-declaration [path] [--check] [--json]",
+		examples: [
+			"apifuse migrate-operation-declaration .",
+			"apifuse migrate-operation-declaration . --check --json",
+		],
+		modulePath: "./apifuse-migrate-operation-declaration",
+	},
 	"submit-check": {
 		name: "submit-check",
 		summary:
@@ -103,6 +133,9 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"create",
 	"dev",
 	"check",
+	"sync-assets",
+	"migrate-shape",
+	"migrate-operation-declaration",
 	"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 = [
@@ -21,7 +26,7 @@ export const CATEGORY_OPTIONS = [
 	"other",
 ] as const;
 export const AUTH_MODE_OPTIONS = ["none", "platform-managed", "credentials", "oauth2"] as const;
-export const RUNTIME_OPTIONS = ["standard", "browser"] as const;
+export const RUNTIME_OPTIONS = ["standard", "shared", "browser"] as const;
 export const PRESET_OPTIONS = ["standalone", "monorepo"] as const;
 
 export type CreateCategory = (typeof CATEGORY_OPTIONS)[number];
@@ -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 = {
@@ -94,7 +102,7 @@ Options:
   --display-name <name>
   --category <category>
   --auth-mode <mode>
-  --runtime <standard|browser>
+  --runtime <standard|shared|browser>
   --yes
   --dry-run
   --json
@@ -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 =
@@ -506,6 +519,12 @@ export async function buildProviderCreatePlan(
 				sdkSpecifier,
 			}),
 		},
+		{
+			path: resolve(providerRoot, "provider.json"),
+			content: await renderTemplate("provider.json.tpl", {
+				PROVIDER_ID: options.name,
+			}),
+		},
 		{
 			path: resolve(providerRoot, "Dockerfile"),
 			content: await renderTemplate("Dockerfile.tpl", {}),
@@ -538,40 +557,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 +616,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 +872,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 +950,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) {