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

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",
@@ -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"
@@ -405,39 +411,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 +465,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 +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);
     }
 }
@@ -754,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));

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;