@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

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 { 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",
@@ -17,12 +18,7 @@ export const CATEGORY_OPTIONS = [
     "communication",
     "other",
 ];
-export const AUTH_MODE_OPTIONS = [
-    "none",
-    "platform-managed",
-    "credentials",
-    "oauth2",
-];
+export const AUTH_MODE_OPTIONS = ["none", "platform-managed", "credentials", "oauth2"];
 export const RUNTIME_OPTIONS = ["standard", "browser"];
 export const PRESET_OPTIONS = ["standalone", "monorepo"];
 const CREATE_CONFIG_SCHEMA = z.object({
@@ -64,9 +60,7 @@ export async function main() {
         return;
     }
     const parsed = parseArgs(normalizedArgs);
-    const config = parsed.configPath
-        ? await loadConfig(parsed.configPath)
-        : undefined;
+    const config = parsed.configPath ? await loadConfig(parsed.configPath) : undefined;
     const resolved = await resolveCreateOptions(parsed, config, process.cwd());
     const plan = await buildProviderCreatePlan(resolved, process.cwd());
     if (resolved.dryRun) {
@@ -174,9 +168,7 @@ async function resolveCreateOptions(parsed, config, cwd) {
         category: parsed.category ?? config?.category,
         authMode: parsed.authMode ?? config?.authMode,
         runtime: parsed.runtime ?? config?.runtime,
-        sdkSpecifier: parsed.sdkSpecifier ??
-            config?.sdkSpecifier ??
-            process.env.APIFUSE__SDK__SPECIFIER,
+        sdkSpecifier: parsed.sdkSpecifier ?? config?.sdkSpecifier ?? process.env.APIFUSE__SDK__SPECIFIER,
         dryRun: parsed.dryRun,
         json: parsed.json,
         yes: parsed.yes,
@@ -267,9 +259,7 @@ async function promptValue(prompt) {
     return result;
 }
 export async function buildProviderCreatePlan(options, cwd) {
-    const resolvedWorkspaceRoot = options.preset === "monorepo"
-        ? findApifuseInternalWorkspaceRoot(cwd)
-        : undefined;
+    const resolvedWorkspaceRoot = options.preset === "monorepo" ? findApifuseInternalWorkspaceRoot(cwd) : undefined;
     if (options.preset === "monorepo" && !resolvedWorkspaceRoot) {
         throw new Error("Monorepo preset is internal to the APIFuse repository. External bounty workspaces are one-provider repositories; use the standalone default create flow.");
     }
@@ -278,9 +268,7 @@ export async function buildProviderCreatePlan(options, cwd) {
     if (options.outputDir) {
         providerRoot = resolve(cwd, options.outputDir);
         installCwd =
-            options.preset === "monorepo" && resolvedWorkspaceRoot
-                ? resolvedWorkspaceRoot
-                : providerRoot;
+            options.preset === "monorepo" && resolvedWorkspaceRoot ? resolvedWorkspaceRoot : providerRoot;
     }
     else if (options.preset === "monorepo" && resolvedWorkspaceRoot) {
         providerRoot = resolve(resolvedWorkspaceRoot, "providers", options.name);
@@ -293,14 +281,18 @@ export async function buildProviderCreatePlan(options, cwd) {
     if (existsSync(providerRoot)) {
         throw new Error(`Target directory already exists: ${providerRoot}`);
     }
-    if (options.sdkSpecifier?.startsWith("workspace:") &&
-        !resolvedWorkspaceRoot) {
+    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"
@@ -420,6 +412,20 @@ export async function buildProviderCreatePlan(options, cwd) {
             }),
         },
     ];
+    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,
@@ -434,7 +440,7 @@ export async function buildProviderCreatePlan(options, cwd) {
         validationCommands: [
             "bun run check",
             "bun run type-check",
-            "bun run submit-check",
+            "bun run submit-check -- --smoke",
             "bun run test",
         ],
         workspaceRoot: resolvedWorkspaceRoot,
@@ -459,9 +465,9 @@ 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 .",
-            "perf:sample": "apifuse perf . --operation ping --runs 3",
             start: "bun start.ts",
         },
         dependencies: {
@@ -544,8 +550,8 @@ function renderAuthBlock(authMode) {
             return `{
     mode: "credentials",
     flow: {
-      start: async () => ({
-        kind: "input",
+      start: async (_ctx) => ({
+        kind: "form",
         turnId: crypto.randomUUID(),
         expectedInput: {
           schema: {
@@ -588,7 +594,7 @@ function renderAuthBlock(authMode) {
             return `{
     mode: "oauth2",
     flow: {
-      start: async () => ({
+      start: async (_ctx) => ({
         kind: "redirect",
         turnId: crypto.randomUUID(),
         data: {
@@ -679,6 +685,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);
     }
 }
@@ -716,9 +729,7 @@ async function runCommand(command, cwd, jsonMode) {
                 resolvePromise();
                 return;
             }
-            rejectPromise(new Error(`Command failed (${command}) in ${cwd}${stdout || stderr
-                ? `\n${[stdout, stderr].filter(Boolean).join("\n")}`
-                : ""}`));
+            rejectPromise(new Error(`Command failed (${command}) in ${cwd}${stdout || stderr ? `\n${[stdout, stderr].filter(Boolean).join("\n")}` : ""}`));
         });
     });
 }
@@ -739,7 +750,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));
@@ -752,7 +766,7 @@ function printResult(plan, jsonMode, dryRun) {
         console.log(`Validation: (cd ${plan.providerRoot} && ${command})`);
     }
     console.log(`Next local dev: ${plan.nextDevCommand}`);
-    console.log("Submission evidence: run `bun run submit-check`, save the generated report, and note `/health` plus `POST /v1/{operation}` smoke results.");
+    console.log("Submission evidence: run `bun run submit-check -- --smoke` to archive measured `/health` and `POST /v1/{operation}` results.");
     if (plan.files.some((file) => file.content.includes('runtime: "browser"'))) {
         console.log("Browser runtime: run `bunx playwright install chromium` locally or set `APIFUSE__CDP_POOL__URL` before browser-backed smoke tests.");
     }

package/dist/cli/prompt-assets.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SDK-managed agent prompt assets.
+ *
+ * `apifuse create` scaffolds these files, `apifuse sync-assets` regenerates
+ * them in an existing provider root, and `apifuse check` / `submit-check`
+ * enforce that they byte-match the installed SDK version (fail closed).
+ *
+ * Layout contract:
+ * - AGENTS.md                     — real file (agent guide)
+ * - CLAUDE.md                     — symlink -> AGENTS.md
+ * - .agents/skills/<skill>/SKILL.md — real files
+ * - .agents/skills/upstream-notes/README.md — real file
+ * - .claude / .codex              — symlinks -> .agents
+ * - .apifuse/prompt-assets.json   — manifest (schema v2), written last
+ */
+export declare const PROMPT_ASSET_MANIFEST_PATH = ".apifuse/prompt-assets.json";
+export declare const PROMPT_ASSET_MANIFEST_SCHEMA_VERSION = 2;
+export declare const PROMPT_ASSET_SYNC_REMEDIATION = "Run `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate the SDK-managed agent prompt assets.";
+export declare const PROMPT_ASSET_SYMLINKS: Readonly<Record<string, string>>;
+/** Relative asset paths whose content is rendered from `<path>.tpl`. */
+export declare const PROMPT_ASSET_FILE_PATHS: readonly string[];
+export type PromptAssetKind = "file" | "symlink";
+export type PromptAssetEntry = {
+    /** Provider-root-relative path (POSIX separators). */
+    path: string;
+    /** File content, or the symlink target for kind "symlink". */
+    content: string;
+    kind: PromptAssetKind;
+};
+export type PromptAssetTemplateRenderer = (fileName: string, values: Record<string, string>) => string | Promise<string>;
+export type PromptAssetVerification = {
+    ok: boolean;
+    /** Expected paths (or the manifest) absent on disk. */
+    missing: string[];
+    /** Manifest recorded for a different SDK version than the installed one. */
+    stale: string[];
+    /** Files/symlinks/manifest whose bytes or target differ from the regenerated set. */
+    modified: string[];
+    /** Legacy layout remnants (top-level skills/). */
+    legacy: string[];
+    /** Entries inside `.agents/` that are not part of the managed asset set. */
+    unexpected: string[];
+};
+export type PromptAssetSyncResult = {
+    changed: boolean;
+    removed: string[];
+    wroteFiles: string[];
+    createdSymlinks: string[];
+    manifestPath: string;
+};
+/**
+ * Build the full managed asset entry list (files first, symlinks after,
+ * manifest excluded). The renderer is injected so `apifuse create` can reuse
+ * its own template renderer; sync/verify use the SDK-internal renderer.
+ */
+export declare function buildPromptAssetPlanEntries(renderTemplate: PromptAssetTemplateRenderer): Promise<PromptAssetEntry[]>;
+export declare function buildPromptAssetPlanEntriesSync(): PromptAssetEntry[];
+/**
+ * Deterministic manifest serialization: schema v2, 2-space JSON, trailing
+ * newline, sorted paths (including symlink paths, excluding the manifest
+ * itself). `sdkVersion` + `paths` keep their v1 semantics so older parsers
+ * keep working; `schemaVersion` and `symlinks` are additive.
+ */
+export declare function buildPromptAssetManifest(entries: readonly PromptAssetEntry[], sdkVersion: string): string;
+export declare function installedSdkVersion(): string;
+/**
+ * Verify the on-disk prompt assets against the set regenerated from the
+ * installed SDK. Uses lstat/readlink for symlinks (never follows), byte
+ * comparison for files, and exact-version comparison for the manifest.
+ */
+export declare function verifyPromptAssets(providerRoot: string): PromptAssetVerification;
+export declare function formatPromptAssetIssues(verification: PromptAssetVerification): string[];
+/**
+ * Regenerate the full managed asset set for the installed SDK version in an
+ * existing provider root. Deletes legacy managed paths first (top-level
+ * skills/**, plus manifest-listed paths that left the set — restricted to
+ * managed namespaces with no symlinked ancestors), writes files, replaces
+ * symlinks, and writes the manifest last. Idempotent.
+ */
+export declare function syncPromptAssets(providerRoot: string): PromptAssetSyncResult;