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

package/dist/cli/create.d.ts

@@ -1,7 +1,7 @@
 export declare const PROVIDER_NAME_REGEX: RegExp;
 export declare const CATEGORY_OPTIONS: readonly ["developer-tools", "finance", "commerce", "productivity", "marketing", "data", "communication", "other"];
 export declare const AUTH_MODE_OPTIONS: readonly ["none", "platform-managed", "credentials", "oauth2"];
-export declare const RUNTIME_OPTIONS: readonly ["standard", "browser"];
+export declare const RUNTIME_OPTIONS: readonly ["standard", "shared", "browser"];
 export declare const PRESET_OPTIONS: readonly ["standalone", "monorepo"];
 export type CreateCategory = (typeof CATEGORY_OPTIONS)[number];
 export type CreateAuthMode = (typeof AUTH_MODE_OPTIONS)[number];
@@ -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",
@@ -18,7 +19,7 @@ export const CATEGORY_OPTIONS = [
     "other",
 ];
 export const AUTH_MODE_OPTIONS = ["none", "platform-managed", "credentials", "oauth2"];
-export const RUNTIME_OPTIONS = ["standard", "browser"];
+export const RUNTIME_OPTIONS = ["standard", "shared", "browser"];
 export const PRESET_OPTIONS = ["standalone", "monorepo"];
 const CREATE_CONFIG_SCHEMA = z.object({
     authMode: z.enum(AUTH_MODE_OPTIONS).optional(),
@@ -45,7 +46,7 @@ Options:
   --display-name <name>
   --category <category>
   --auth-mode <mode>
-  --runtime <standard|browser>
+  --runtime <standard|shared|browser>
   --yes
   --dry-run
   --json
@@ -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"
@@ -373,6 +379,12 @@ export async function buildProviderCreatePlan(options, cwd) {
                 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", {}),
@@ -405,39 +417,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 +471,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 +691,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 +756,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/migrate-operation-declaration.d.ts

@@ -0,0 +1,59 @@
+export type OperationDeclarationRefusalReason = "no_safety" | "safety_conflict" | "locale_key_conflict" | "connection_mode_conflict" | "execution_conflict" | "approval_conflict" | "non_literal" | "unsupported_member" | "factory_composed_operations" | "source_syntax" | "codemod_syntax" | "missing_english_locale" | "operation_id_unresolved" | "examples_conflict" | "locale_todo_conflict";
+export type OperationDeclarationRefusal = {
+    readonly file: string;
+    readonly operationKey: string;
+    readonly reason: OperationDeclarationRefusalReason;
+    readonly detail: string;
+};
+export type LocaleTodo = {
+    readonly localeFile: string;
+    readonly operationKey: string;
+    readonly key: string;
+    readonly originalProse: string;
+};
+export type OperationDeclarationMigration = {
+    readonly status: "migrated";
+    readonly code: string;
+    readonly operations: number;
+    readonly localeTodos: readonly LocaleTodo[];
+} | {
+    readonly status: "unchanged";
+    readonly code: string;
+    readonly operations: number;
+} | {
+    readonly status: "refused";
+    readonly refusals: readonly OperationDeclarationRefusal[];
+};
+export type OperationDeclarationMigrationOptions = {
+    /** Exact operation ids proven from a static operations map, keyed by local binding name. */
+    readonly operationIds?: ReadonlyMap<string, string>;
+    /** Locale paths relative to the provider root. */
+    readonly localeFiles?: readonly string[];
+};
+/**
+ * Rewrite every operation declaration in one TypeScript module.
+ *
+ * The function is file-atomic: a single refusal discards every planned edit.
+ * It uses AST ranges as a string/comment/template-aware brace balancer and
+ * copies every untouched source slice byte-for-byte.
+ */
+export declare function migrateOperationDeclaration(sourceText: string, fileName: string, options?: OperationDeclarationMigrationOptions): OperationDeclarationMigration;
+/** Parse a proposed rewrite and classify a codemod-introduced syntax failure. */
+export declare function verifyOperationDeclarationRewrite(code: string, fileName: string): OperationDeclarationRefusal | undefined;
+export type OperationDeclarationRepositoryResult = {
+    readonly status: "migrated" | "would-migrate" | "unchanged";
+    readonly providerRoot: string;
+    readonly changedFiles: readonly string[];
+    readonly operationCount: number;
+    readonly sidecar?: string;
+    readonly localeTodoCount: number;
+} | {
+    readonly status: "refused";
+    readonly providerRoot: string;
+    readonly refusals: readonly OperationDeclarationRefusal[];
+};
+/** Run the file transform repository-wide, committing writes only if every file is provable. */
+export declare function migrateOperationDeclarationRepository(providerRootInput: string, options?: {
+    readonly check?: boolean;
+}): OperationDeclarationRepositoryResult;
+export declare function renderLocaleTodoSidecar(todos: readonly LocaleTodo[]): string;