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

package/dist/cli/prompt-assets.js

@@ -0,0 +1,743 @@
+import { lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmdirSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import packageJson from "../../package.json";
+/**
+ * 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 const PROMPT_ASSET_MANIFEST_PATH = ".apifuse/prompt-assets.json";
+export const PROMPT_ASSET_MANIFEST_SCHEMA_VERSION = 2;
+export const PROMPT_ASSET_SYNC_REMEDIATION = "Run `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate the SDK-managed agent prompt assets.";
+export const PROMPT_ASSET_SYMLINKS = {
+    "CLAUDE.md": "AGENTS.md",
+    ".claude": ".agents",
+    ".codex": ".agents",
+};
+/** Legacy layout remnants that must not survive a sync (pre-.agents layout). */
+const LEGACY_TOP_LEVEL_SKILLS_DIR = "skills";
+/**
+ * Contributor-owned zone. `.agents/skills/upstream-notes/README.md` is
+ * SDK-managed (pristine-verified), but the README template explicitly
+ * instructs contributors to ADD per-vendor note files as sibling entries, and
+ * reviewers treat them as submission quality. Any file under this directory
+ * OTHER than README.md is therefore contributor-owned: the freshness gate must
+ * never flag it `unexpected`, and sync-assets (including its legacy cleanup)
+ * must never delete it — legacy authored notes are relocated here, not dropped.
+ */
+const UPSTREAM_NOTES_DIR = ".agents/skills/upstream-notes";
+const UPSTREAM_NOTES_README = `${UPSTREAM_NOTES_DIR}/README.md`;
+/**
+ * True for real, contributor-authored entries inside the upstream-notes zone
+ * (everything under it except the managed README.md). Symlinks are never
+ * treated as contributor-owned — callers must gate this behind an lstat that
+ * excludes symlinks so the exemption can never smuggle a path that escapes the
+ * provider root by naming it under upstream-notes.
+ */
+function isContributorOwnedUpstreamNotesPath(relativePath) {
+    return (relativePath.startsWith(`${UPSTREAM_NOTES_DIR}/`) && relativePath !== UPSTREAM_NOTES_README);
+}
+/** Relative asset paths whose content is rendered from `<path>.tpl`. */
+export const PROMPT_ASSET_FILE_PATHS = [
+    "AGENTS.md",
+    ".agents/skills/normalization-standards/SKILL.md",
+    ".agents/skills/upstream-contract-verification/SKILL.md",
+    ".agents/skills/fixtures-and-recording/SKILL.md",
+    ".agents/skills/pagination-and-counts/SKILL.md",
+    ".agents/skills/health-checks-and-fail-closed/SKILL.md",
+    ".agents/skills/upstream-notes/README.md",
+];
+const TEMPLATE_DIR = fileURLToPath(new URL("./templates/provider/", import.meta.url));
+function renderPromptAssetTemplateSync(fileName) {
+    const template = readFileSync(resolve(TEMPLATE_DIR, fileName), "utf8");
+    // Prompt asset templates take no values; mirror create.ts renderTemplate
+    // semantics (unknown keys render as empty strings) for byte-identical output.
+    return template.replace(/\{\{([A-Z_]+)\}\}/g, () => "");
+}
+/**
+ * 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 async function buildPromptAssetPlanEntries(renderTemplate) {
+    const entries = [];
+    for (const assetPath of PROMPT_ASSET_FILE_PATHS) {
+        entries.push({
+            path: assetPath,
+            content: await renderTemplate(`${assetPath}.tpl`, {}),
+            kind: "file",
+        });
+    }
+    for (const [linkPath, target] of Object.entries(PROMPT_ASSET_SYMLINKS)) {
+        entries.push({ path: linkPath, content: target, kind: "symlink" });
+    }
+    return entries;
+}
+export function buildPromptAssetPlanEntriesSync() {
+    const entries = [];
+    for (const assetPath of PROMPT_ASSET_FILE_PATHS) {
+        entries.push({
+            path: assetPath,
+            content: renderPromptAssetTemplateSync(`${assetPath}.tpl`),
+            kind: "file",
+        });
+    }
+    for (const [linkPath, target] of Object.entries(PROMPT_ASSET_SYMLINKS)) {
+        entries.push({ path: linkPath, content: target, kind: "symlink" });
+    }
+    return entries;
+}
+/**
+ * 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 function buildPromptAssetManifest(entries, sdkVersion) {
+    const paths = entries.map((entry) => entry.path).sort();
+    return `${JSON.stringify({
+        schemaVersion: PROMPT_ASSET_MANIFEST_SCHEMA_VERSION,
+        sdkVersion,
+        paths,
+        symlinks: PROMPT_ASSET_SYMLINKS,
+    }, null, 2)}\n`;
+}
+export function installedSdkVersion() {
+    return packageJson.version;
+}
+function lstatSafe(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readManifestRaw(manifestAbsPath) {
+    const stat = lstatSafe(manifestAbsPath);
+    if (!stat?.isFile()) {
+        return undefined;
+    }
+    return readFileSync(manifestAbsPath, "utf8");
+}
+function parseManifest(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) {
+            return { paths: [] };
+        }
+        const record = parsed;
+        const sdkVersion = typeof record.sdkVersion === "string" ? record.sdkVersion : undefined;
+        const paths = Array.isArray(record.paths)
+            ? record.paths.filter((value) => typeof value === "string")
+            : [];
+        return { sdkVersion, paths };
+    }
+    catch {
+        return { paths: [] };
+    }
+}
+/** Reject manifest paths that could escape the provider root. */
+function isSafeRelativeAssetPath(relativePath) {
+    if (!relativePath || relativePath.startsWith("/") || relativePath.includes("\\")) {
+        return false;
+    }
+    const segments = relativePath.split("/");
+    return segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/**
+ * Namespaces the SDK has ever managed. Manifest-driven orphan cleanup may
+ * only delete inside these — a pre-existing manifest is untrusted repository
+ * content (bounty submissions are adversarial), so listing e.g. `src/index.ts`
+ * or `.git/config` must never make sync-assets delete it.
+ */
+const MANAGED_TOP_LEVEL_NAMES = new Set([
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".claude",
+    ".codex",
+    ".agents",
+    ".apifuse",
+    LEGACY_TOP_LEVEL_SKILLS_DIR,
+]);
+const MANAGED_PATH_PREFIXES = [
+    ".agents/",
+    ".apifuse/",
+    `${LEGACY_TOP_LEVEL_SKILLS_DIR}/`,
+];
+function isManagedNamespacePath(relativePath) {
+    return (MANAGED_TOP_LEVEL_NAMES.has(relativePath) ||
+        MANAGED_PATH_PREFIXES.some((prefix) => relativePath.startsWith(prefix)));
+}
+/**
+ * Root of the auto-loaded skill tree. `.claude`/`.codex` symlink onto `.agents`,
+ * so every agent CLI loads `.agents/skills/<name>/` as guidance — this subtree,
+ * and only this subtree, is the guidance-injection vector the freshness gate
+ * polices for unauthorized content.
+ */
+const AGENTS_SKILLS_DIR = ".agents/skills";
+/**
+ * Skill directory names the SDK authorizes: the managed skills plus the
+ * contributor-owned `upstream-notes` zone. Derived from PROMPT_ASSET_FILE_PATHS
+ * (`.agents/skills/<name>/...`), so upstream-notes is included via its managed
+ * README. Any OTHER directory directly under `.agents/skills/` is an injected
+ * skill.
+ */
+const AUTHORIZED_SKILL_DIR_NAMES = new Set(PROMPT_ASSET_FILE_PATHS.filter((assetPath) => assetPath.startsWith(`${AGENTS_SKILLS_DIR}/`)).map((assetPath) => assetPath.split("/")[2]));
+/**
+ * Every managed directory ancestor implied by the real-file asset paths, sorted
+ * parent-before-child (fewest path segments first): `.agents`, `.agents/skills`,
+ * `.agents/skills/<each managed skill>`, `.agents/skills/upstream-notes`, … .
+ * Derived generically from PROMPT_ASSET_FILE_PATHS so no level is ever missed;
+ * sync normalizes each into a REAL directory before any relocation/comparison/
+ * write so nothing resolves through a symlink to an outside location.
+ */
+const MANAGED_DIRECTORY_ANCESTORS = (() => {
+    const dirs = new Set();
+    for (const assetPath of PROMPT_ASSET_FILE_PATHS) {
+        const segments = assetPath.split("/");
+        for (let end = 1; end < segments.length; end += 1) {
+            dirs.add(segments.slice(0, end).join("/"));
+        }
+    }
+    return [...dirs].sort((a, b) => a.split("/").length - b.split("/").length);
+})();
+/**
+ * Enumerate the guidance-injection risks under `.agents/skills/` — and ONLY
+ * those. Two things are flagged (never followed, never deleted by sync):
+ *   1. an unauthorized skill directory `.agents/skills/<name>/` whose <name> is
+ *      neither a managed skill nor `upstream-notes` (an injected skill), and
+ *   2. any SYMLINK anywhere under `.agents/skills/` (at any depth).
+ *
+ * Everything else under `.agents/` is tool/user content that legitimately lands
+ * there through the `.claude`/`.codex` symlinks — `settings.json`,
+ * `config.toml`, `commands/`, `hooks/`, `references/`, authored files inside
+ * `.agents/skills/upstream-notes/`, etc. — and is NEVER flagged or swept. Real
+ * subdirectories inside authorized skills are still walked so nested symlinks
+ * stay visible. Returns sorted provider-root-relative paths (dirs get a
+ * trailing `/`). No-op when `.agents/skills` is missing or a symlink.
+ */
+function findUnexpectedAgentEntries(providerRoot) {
+    const skillsStat = lstatSafe(join(providerRoot, AGENTS_SKILLS_DIR));
+    if (!skillsStat?.isDirectory()) {
+        return [];
+    }
+    const unexpected = [];
+    const readDirentsSafe = (absDir) => {
+        try {
+            return readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+    };
+    // Recurse through an authorized skill directory, flagging only symlinks
+    // (never following them); real files/dirs inside are the skill's content.
+    const flagNestedSymlinks = (relativeDir) => {
+        for (const dirent of readDirentsSafe(join(providerRoot, relativeDir))) {
+            const relativePath = `${relativeDir}/${dirent.name}`;
+            if (dirent.isSymbolicLink()) {
+                unexpected.push(relativePath);
+            }
+            else if (dirent.isDirectory()) {
+                flagNestedSymlinks(relativePath);
+            }
+        }
+    };
+    for (const dirent of readDirentsSafe(join(providerRoot, AGENTS_SKILLS_DIR))) {
+        const relativePath = `${AGENTS_SKILLS_DIR}/${dirent.name}`;
+        if (dirent.isSymbolicLink()) {
+            // A symlink directly under the skills tree — the injection vector.
+            unexpected.push(relativePath);
+        }
+        else if (dirent.isDirectory()) {
+            if (AUTHORIZED_SKILL_DIR_NAMES.has(dirent.name)) {
+                flagNestedSymlinks(relativePath);
+            }
+            else {
+                // An unauthorized skill directory — flagged, never deleted.
+                unexpected.push(`${relativePath}/`);
+            }
+        }
+        // Non-skill regular files directly under `.agents/skills/` are ignored.
+    }
+    return unexpected.sort();
+}
+/**
+ * First ancestor directory of `relativePath` (relative, final component
+ * excluded) that exists on disk as a symlink — undefined when every existing
+ * ancestor is a real directory. The lexical safety check cannot catch this:
+ * `join()` never follows links, but rmSync/readFileSync/writeFileSync resolve
+ * intermediate symlink components, so `linkdir -> /outside` plus a manifest
+ * path `linkdir/x` would otherwise read or delete outside the provider root.
+ */
+function findSymlinkAncestor(providerRoot, relativePath) {
+    const segments = relativePath.split("/").slice(0, -1);
+    let currentRelative = "";
+    for (const segment of segments) {
+        currentRelative = currentRelative === "" ? segment : `${currentRelative}/${segment}`;
+        const stat = lstatSafe(join(providerRoot, currentRelative));
+        if (!stat) {
+            return undefined;
+        }
+        if (stat.isSymbolicLink()) {
+            return currentRelative;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 function verifyPromptAssets(providerRoot) {
+    const entries = buildPromptAssetPlanEntriesSync();
+    const missing = [];
+    const stale = [];
+    const modified = [];
+    const legacy = [];
+    // Any top-level `skills` entry is legacy — directory, regular file, or
+    // symlink (a `skills -> elsewhere` link would keep serving stale prompt
+    // content to agents following pre-migration references). This mirrors the
+    // sync-assets removal predicate so verify-green always implies sync-no-op.
+    const legacySkillsStat = lstatSafe(join(providerRoot, LEGACY_TOP_LEVEL_SKILLS_DIR));
+    if (legacySkillsStat) {
+        const kind = legacySkillsStat.isDirectory()
+            ? "directory"
+            : legacySkillsStat.isSymbolicLink()
+                ? "symlink"
+                : "file";
+        legacy.push(`${LEGACY_TOP_LEVEL_SKILLS_DIR}/ (legacy top-level skills ${kind}; the managed copy lives in .agents/skills/)`);
+    }
+    // Managed assets must not resolve through symlinked directories: the
+    // layout contract allows symlinks only at CLAUDE.md/.claude/.codex. A
+    // symlinked `.agents` (or `.apifuse`) would let the effective prompt
+    // content live outside the repository while byte checks still pass.
+    const flaggedSymlinkAncestors = new Set();
+    const recordSymlinkAncestor = (relativePath) => {
+        const ancestor = findSymlinkAncestor(providerRoot, relativePath);
+        if (ancestor === undefined) {
+            return false;
+        }
+        if (!flaggedSymlinkAncestors.has(ancestor)) {
+            flaggedSymlinkAncestors.add(ancestor);
+            modified.push(`${ancestor} (expected a real directory, found a symlink)`);
+        }
+        return true;
+    };
+    const manifestAbsPath = join(providerRoot, PROMPT_ASSET_MANIFEST_PATH);
+    const manifestRaw = recordSymlinkAncestor(PROMPT_ASSET_MANIFEST_PATH)
+        ? undefined
+        : readManifestRaw(manifestAbsPath);
+    if (manifestRaw === undefined) {
+        missing.push(PROMPT_ASSET_MANIFEST_PATH);
+    }
+    else {
+        const expectedManifest = buildPromptAssetManifest(entries, packageJson.version);
+        const { sdkVersion } = parseManifest(manifestRaw);
+        if (sdkVersion !== packageJson.version) {
+            stale.push(`${PROMPT_ASSET_MANIFEST_PATH} (sdkVersion ${sdkVersion ?? "unreadable"} != installed ${packageJson.version})`);
+        }
+        else if (manifestRaw !== expectedManifest) {
+            modified.push(`${PROMPT_ASSET_MANIFEST_PATH} (differs from the regenerated manifest)`);
+        }
+    }
+    for (const entry of entries) {
+        if (recordSymlinkAncestor(entry.path)) {
+            continue;
+        }
+        const absPath = join(providerRoot, entry.path);
+        const stat = lstatSafe(absPath);
+        if (!stat) {
+            missing.push(entry.path);
+            continue;
+        }
+        if (entry.kind === "symlink") {
+            if (!stat.isSymbolicLink()) {
+                // A real directory here is user agent config, not a stale asset:
+                // report a distinct, actionable reason (never a generic `unexpected`,
+                // and it is never swept — findUnexpectedAgentEntries only walks
+                // `.agents/`). sync-assets throws on it rather than migrating.
+                modified.push(stat.isDirectory()
+                    ? `${entry.path} (must be a symlink to ${entry.content}; migrate its contents first)`
+                    : `${entry.path} (expected symlink -> ${entry.content})`);
+                continue;
+            }
+            const target = readlinkSync(absPath);
+            if (target !== entry.content) {
+                modified.push(`${entry.path} (symlink -> ${target}, expected -> ${entry.content})`);
+            }
+            continue;
+        }
+        if (!stat.isFile()) {
+            modified.push(`${entry.path} (expected a regular file)`);
+            continue;
+        }
+        if (readFileSync(absPath, "utf8") !== entry.content) {
+            modified.push(`${entry.path} (content differs from the installed SDK template)`);
+        }
+    }
+    // Extra, unlisted files under `.agents/` must fail closed: the freshness
+    // gate would otherwise let a contributor inject agent guidance that byte
+    // checks over the fixed expected set never see.
+    const unexpected = findUnexpectedAgentEntries(providerRoot);
+    return {
+        ok: missing.length === 0 &&
+            stale.length === 0 &&
+            modified.length === 0 &&
+            legacy.length === 0 &&
+            unexpected.length === 0,
+        missing,
+        stale,
+        modified,
+        legacy,
+        unexpected,
+    };
+}
+export function formatPromptAssetIssues(verification) {
+    return [
+        ...verification.missing.map((item) => `missing: ${item}`),
+        ...verification.stale.map((item) => `stale: ${item}`),
+        ...verification.modified.map((item) => `modified: ${item}`),
+        ...verification.legacy.map((item) => `legacy: ${item}`),
+        ...verification.unexpected.map((item) => `unexpected: ${item}`),
+    ];
+}
+function removeEmptyParentDirectories(providerRoot, startDirectory) {
+    const rootPath = resolve(providerRoot);
+    let currentDirectory = resolve(startDirectory);
+    while (currentDirectory.startsWith(`${rootPath}/`) && currentDirectory !== rootPath) {
+        try {
+            rmdirSync(currentDirectory); // only succeeds when empty
+        }
+        catch {
+            return;
+        }
+        currentDirectory = dirname(currentDirectory);
+    }
+}
+/** Remove any non-directory ancestor blocking a managed file path, then mkdir -p. */
+function ensureParentDirectory(providerRoot, relativeFilePath) {
+    const segments = relativeFilePath.split("/").slice(0, -1);
+    let currentPath = providerRoot;
+    for (const segment of segments) {
+        currentPath = join(currentPath, segment);
+        const stat = lstatSafe(currentPath);
+        if (stat && !stat.isDirectory()) {
+            rmSync(currentPath, { recursive: true, force: true });
+        }
+    }
+    mkdirSync(join(providerRoot, segments.join("/")), { recursive: true });
+}
+/**
+ * Relocate contributor-authored files from the legacy top-level
+ * `skills/upstream-notes/` into the managed `.agents/skills/upstream-notes/`
+ * zone before the legacy `skills/` tree is deleted. The legacy README.md is
+ * skipped (regenerated from the template). Only real files reached through real
+ * directories are moved — symlinks are never relocated or followed, so a
+ * hostile `skills/upstream-notes/link -> /outside` can never copy content into
+ * or out of the provider root.
+ *
+ * A newer `.agents` note is never overwritten. When the destination already
+ * exists: identical bytes mean the legacy copy is redundant (dropped, no
+ * write); differing bytes (or a non-regular-file destination) mean the legacy
+ * content is written to the first free `<name>.legacy[.N]<ext>` path alongside
+ * it so both versions are retained. Returns the paths actually written.
+ *
+ * Called only when the legacy `skills/` entry is itself a real directory.
+ */
+/**
+ * First non-colliding conflict path alongside `destRelativePath`, inserting a
+ * `.legacy` marker before the extension: `foo.md` -> `foo.legacy.md`, then
+ * `foo.legacy.1.md`, `foo.legacy.2.md`, … Uses lstat (never follows) so an
+ * existing symlink at a candidate name still counts as taken.
+ */
+function firstFreeConflictPath(providerRoot, destRelativePath) {
+    const slash = destRelativePath.lastIndexOf("/");
+    const dir = destRelativePath.slice(0, slash);
+    const filename = destRelativePath.slice(slash + 1);
+    const dot = filename.lastIndexOf(".");
+    const stem = dot > 0 ? filename.slice(0, dot) : filename;
+    const ext = dot > 0 ? filename.slice(dot) : "";
+    for (let index = 0;; index += 1) {
+        const candidateName = index === 0 ? `${stem}.legacy${ext}` : `${stem}.legacy.${index}${ext}`;
+        const candidateRelative = `${dir}/${candidateName}`;
+        if (!lstatSafe(join(providerRoot, candidateRelative))) {
+            return candidateRelative;
+        }
+    }
+}
+function relocateLegacyUpstreamNotes(providerRoot) {
+    const legacyNotesDir = `${LEGACY_TOP_LEVEL_SKILLS_DIR}/upstream-notes`;
+    const legacyNotesStat = lstatSafe(join(providerRoot, legacyNotesDir));
+    if (!legacyNotesStat?.isDirectory()) {
+        return [];
+    }
+    const relocated = [];
+    const readDirentsSafe = (absDir) => {
+        try {
+            return readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+    };
+    const walk = (relativeDir) => {
+        for (const dirent of readDirentsSafe(join(providerRoot, relativeDir))) {
+            const relativePath = `${relativeDir}/${dirent.name}`;
+            if (dirent.isSymbolicLink()) {
+                continue; // never relocate a symlink or recurse through it
+            }
+            if (dirent.isDirectory()) {
+                walk(relativePath);
+                continue;
+            }
+            if (!dirent.isFile()) {
+                continue;
+            }
+            const subPath = relativePath.slice(`${legacyNotesDir}/`.length);
+            if (subPath === "README.md") {
+                continue; // managed asset, regenerated from the template
+            }
+            const destRelativePath = `${UPSTREAM_NOTES_DIR}/${subPath}`;
+            const contents = readFileSync(join(providerRoot, relativePath));
+            const destAbsPath = join(providerRoot, destRelativePath);
+            const destStat = lstatSafe(destAbsPath);
+            if (!destStat) {
+                // No collision — relocate the legacy note as-is.
+                ensureParentDirectory(providerRoot, destRelativePath);
+                writeFileSync(destAbsPath, contents);
+                relocated.push(destRelativePath);
+                continue;
+            }
+            if (destStat.isFile() && readFileSync(destAbsPath).equals(contents)) {
+                // A byte-identical note already lives at the destination; the legacy
+                // copy is redundant. Write nothing — the caller removes the legacy
+                // tree, dropping the duplicate without touching the newer file.
+                continue;
+            }
+            // Destination exists with different bytes (or is not a plain file):
+            // never overwrite it. Retain both by writing the legacy content to the
+            // first free `<name>.legacy[.N]<ext>` path beside it.
+            const conflictRelativePath = firstFreeConflictPath(providerRoot, destRelativePath);
+            ensureParentDirectory(providerRoot, conflictRelativePath);
+            writeFileSync(join(providerRoot, conflictRelativePath), contents);
+            relocated.push(conflictRelativePath);
+        }
+    };
+    walk(legacyNotesDir);
+    return relocated;
+}
+/** Sorted immediate child names of a directory (empty on any read error). */
+function readTopLevelEntryNames(absDir) {
+    try {
+        return readdirSync(absDir).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Actionable error for a pre-existing REAL directory occupying a managed
+ * symlink path (`.claude`/`.codex`). The agent-asset layout requires a symlink
+ * to `.agents`; sync-assets never merges or deletes such a directory (either
+ * would risk destroying user agent config), so it fails loudly and tells the
+ * user to reconcile it by hand. Deterministic and idempotent: once the user
+ * moves/removes the contents, the next run creates the symlink and stays green.
+ */
+function realDirectorySymlinkConflictMessage(providerRoot, entryPath, target) {
+    const names = readTopLevelEntryNames(join(providerRoot, entryPath));
+    const contents = names.length > 0 ? names.join(", ") : "(empty)";
+    return (`${entryPath}/ is a real directory containing [${contents}]. ` +
+        `The APIFuse agent-asset layout requires ${entryPath} to be a symlink to ${target}. ` +
+        `Move or remove its contents (e.g. into ${target}/) and re-run \`apifuse sync-assets .\`.`);
+}
+/**
+ * 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 function syncPromptAssets(providerRoot) {
+    const entries = buildPromptAssetPlanEntriesSync();
+    const manifestContent = buildPromptAssetManifest(entries, packageJson.version);
+    const manifestAbsPath = join(providerRoot, PROMPT_ASSET_MANIFEST_PATH);
+    const expectedPaths = new Set([
+        ...entries.map((entry) => entry.path),
+        PROMPT_ASSET_MANIFEST_PATH,
+    ]);
+    const removed = [];
+    const wroteFiles = [];
+    const createdSymlinks = [];
+    // 0. Normalize the ENTIRE managed directory ancestor chain into REAL
+    // directories BEFORE any relocation, comparison, or managed-file write. If
+    // ANY level (`.agents`, `.agents/skills`, `.agents/skills/upstream-notes`, a
+    // managed skill dir) is a symlink or regular file, a later identity/collision
+    // check or write would resolve THROUGH it to an outside location — e.g. the
+    // legacy upstream-note duplicate check could read an outside file, match
+    // bytes, and drop the note as "redundant"; the link is then replaced with a
+    // real dir and legacy skills/ is removed → silent data loss. Iterating
+    // parent-before-child replaces a symlinked parent before its children are
+    // created. lstat only: a symlink/file is unlinked, never followed, so the
+    // outside target and everything outside the provider root are untouched.
+    for (const managedDir of MANAGED_DIRECTORY_ANCESTORS) {
+        const absDir = join(providerRoot, managedDir);
+        const stat = lstatSafe(absDir);
+        if (stat && !stat.isDirectory()) {
+            rmSync(absDir, { recursive: true, force: true });
+        }
+        mkdirSync(absDir, { recursive: true });
+    }
+    // 1. Legacy top-level skills/ from the pre-.agents layout. Contributor-
+    // authored upstream-notes files are relocated into the managed
+    // .agents/skills/upstream-notes/ zone FIRST (never destroyed); only then is
+    // the legacy tree removed. Relocation runs only when `skills` is a real
+    // directory — a `skills` symlink is unlinked without following it.
+    const legacySkillsAbsPath = join(providerRoot, LEGACY_TOP_LEVEL_SKILLS_DIR);
+    const legacySkillsStat = lstatSafe(legacySkillsAbsPath);
+    if (legacySkillsStat) {
+        if (legacySkillsStat.isDirectory()) {
+            wroteFiles.push(...relocateLegacyUpstreamNotes(providerRoot));
+        }
+        rmSync(legacySkillsAbsPath, { recursive: true, force: true });
+        removed.push(`${LEGACY_TOP_LEVEL_SKILLS_DIR}/`);
+    }
+    // 2. Paths a pre-existing manifest managed that are no longer in the set.
+    // The manifest is untrusted repository content: deletion is restricted to
+    // SDK-managed namespaces, and paths resolving through a symlinked
+    // directory are skipped entirely (rmSync follows intermediate symlinks, so
+    // they could otherwise delete files outside the provider root).
+    const previousManifestRaw = findSymlinkAncestor(providerRoot, PROMPT_ASSET_MANIFEST_PATH) === undefined
+        ? readManifestRaw(manifestAbsPath)
+        : undefined;
+    if (previousManifestRaw !== undefined) {
+        for (const previousPath of parseManifest(previousManifestRaw).paths) {
+            if (expectedPaths.has(previousPath) ||
+                !isSafeRelativeAssetPath(previousPath) ||
+                !isManagedNamespacePath(previousPath) ||
+                isContributorOwnedUpstreamNotesPath(previousPath) ||
+                findSymlinkAncestor(providerRoot, previousPath) !== undefined) {
+                continue;
+            }
+            const absPath = join(providerRoot, previousPath);
+            const orphanStat = lstatSafe(absPath);
+            if (!orphanStat) {
+                continue;
+            }
+            // Never recursively delete a managed-namespace DIRECTORY named by the
+            // (untrusted) manifest: a hostile or stale entry like `.agents/skills`
+            // would otherwise sweep away contributor-authored upstream-notes files
+            // nested inside it. Directories are removed only when already empty;
+            // recursive removal is limited to regular files (and a symlink AT the
+            // path, which rmSync unlinks without following). Individual authored
+            // notes are additionally guarded by isContributorOwnedUpstreamNotesPath.
+            if (orphanStat.isDirectory()) {
+                try {
+                    rmdirSync(absPath); // succeeds only when the directory is empty
+                }
+                catch {
+                    continue;
+                }
+                removed.push(previousPath);
+                removeEmptyParentDirectories(providerRoot, dirname(absPath));
+                continue;
+            }
+            rmSync(absPath, { recursive: true, force: true });
+            removed.push(previousPath);
+            removeEmptyParentDirectories(providerRoot, dirname(absPath));
+        }
+    }
+    // 3. Regular files (byte-identical files are left untouched). When an
+    // ancestor directory is a symlink (e.g. `.agents -> /elsewhere`), the
+    // bytes visible through the link never count as in-sync: the entry is
+    // rewritten and ensureParentDirectory replaces the offending link with a
+    // real directory. The final path is never rmSync'd through such a link.
+    for (const entry of entries) {
+        if (entry.kind !== "file") {
+            continue;
+        }
+        const absPath = join(providerRoot, entry.path);
+        const symlinkAncestor = findSymlinkAncestor(providerRoot, entry.path);
+        const stat = symlinkAncestor === undefined ? lstatSafe(absPath) : undefined;
+        if (stat?.isFile() && readFileSync(absPath, "utf8") === entry.content) {
+            continue;
+        }
+        if (stat) {
+            rmSync(absPath, { recursive: true, force: true });
+        }
+        ensureParentDirectory(providerRoot, entry.path);
+        writeFileSync(absPath, entry.content);
+        wroteFiles.push(entry.path);
+    }
+    // 4. Symlinks — replace whatever occupies the path. A wrong-target symlink
+    // or a regular file carries no user tree and is replaced. But a REAL
+    // DIRECTORY here is pre-existing user agent config (a hand-managed
+    // `.claude/` or `.codex/` with commands/, settings.json, hooks): never
+    // merge or delete it. Fail loudly and idempotently so the user reconciles
+    // it by hand — no data is touched. Correct links are left untouched.
+    for (const entry of entries) {
+        if (entry.kind !== "symlink") {
+            continue;
+        }
+        const absPath = join(providerRoot, entry.path);
+        const symlinkAncestor = findSymlinkAncestor(providerRoot, entry.path);
+        const stat = symlinkAncestor === undefined ? lstatSafe(absPath) : undefined;
+        if (stat?.isSymbolicLink() && readlinkSync(absPath) === entry.content) {
+            continue;
+        }
+        if (stat?.isDirectory()) {
+            throw new Error(realDirectorySymlinkConflictMessage(providerRoot, entry.path, entry.content));
+        }
+        if (stat) {
+            rmSync(absPath, { recursive: true, force: true });
+        }
+        ensureParentDirectory(providerRoot, entry.path);
+        symlinkSync(entry.content, absPath);
+        createdSymlinks.push(`${entry.path} -> ${entry.content}`);
+    }
+    // INVARIANT: sync-assets only writes/repairs the managed asset set + the
+    // managed symlinks and migrates known legacy paths (top-level skills/** with
+    // upstream-notes relocation). It NEVER deletes unrecognized user/tool
+    // content. In particular there is deliberately no sweep of `.agents/`: the
+    // `.claude`/`.codex` symlinks point at `.agents`, so agent CLIs write live
+    // project config there (settings.json, config.toml, commands/, hooks/, …).
+    // Unauthorized injected skills and symlinks under `.agents/skills/` are
+    // surfaced by verifyPromptAssets (the freshness gate) for a human to remove
+    // — they are flagged, never deleted here.
+    // 5. Manifest last so a crash mid-sync never records a fresh manifest.
+    let manifestChanged = false;
+    const manifestStat = findSymlinkAncestor(providerRoot, PROMPT_ASSET_MANIFEST_PATH) === undefined
+        ? lstatSafe(manifestAbsPath)
+        : undefined;
+    if (!(manifestStat?.isFile() && readFileSync(manifestAbsPath, "utf8") === manifestContent)) {
+        if (manifestStat) {
+            rmSync(manifestAbsPath, { recursive: true, force: true });
+        }
+        ensureParentDirectory(providerRoot, PROMPT_ASSET_MANIFEST_PATH);
+        writeFileSync(manifestAbsPath, manifestContent);
+        manifestChanged = true;
+    }
+    return {
+        changed: manifestChanged ||
+            removed.length > 0 ||
+            wroteFiles.length > 0 ||
+            createdSymlinks.length > 0,
+        removed,
+        wroteFiles,
+        createdSymlinks,
+        manifestPath: PROMPT_ASSET_MANIFEST_PATH,
+    };
+}