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

package/dist/cli/migrate-provider-shape.js

@@ -0,0 +1,578 @@
+const ts = await loadTypeScript();
+async function loadTypeScript() {
+    try {
+        return await import("typescript");
+    }
+    catch {
+        console.error("apifuse migrate-shape requires typescript; install it in the workspace running the CLI (bun add -d typescript)");
+        process.exit(1);
+    }
+}
+const DECLARATION_BUILDER_NAME = "buildProvider";
+const PROVIDER_CONTEXT_TYPE_NAME = "ProviderContext";
+const PROVIDER_CONTEXT_OF_TYPE_NAME = "ProviderContextOf";
+const PROVIDER_SDK_PROVIDER_SUBPATH = "@apifuse/provider-sdk/provider";
+/**
+ * Migrate one provider `index.ts` to the two-phase authoring shape.
+ *
+ * Returns the rewritten source on success. Callers MUST treat `skipped` as a
+ * hard stop for that provider — a skipped provider needs a human, and pairing
+ * a pin bump with a skipped migration produces an unloadable module.
+ */
+export function migrateProviderShape(sourceText, fileName = "index.ts") {
+    const source = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, 
+    /* setParentNodes */ true, ts.ScriptKind.TS);
+    const syntaxError = firstSyntaxError(source);
+    if (syntaxError !== undefined) {
+        return { status: "skipped", reason: syntaxError };
+    }
+    const calls = collectDefineProviderCalls(source);
+    if (calls.length === 0) {
+        return {
+            status: "skipped",
+            reason: "No defineProvider(...) call found; this file does not declare a provider.",
+        };
+    }
+    if (calls.length > 1) {
+        return {
+            status: "skipped",
+            reason: `Found ${calls.length} defineProvider(...) calls; the transform rewrites exactly one declaration.`,
+        };
+    }
+    const call = calls[0];
+    if (call === undefined) {
+        return { status: "skipped", reason: "Internal: defineProvider call vanished." };
+    }
+    const exportAssignment = findDefaultExport(source);
+    if (exportAssignment === undefined) {
+        return {
+            status: "skipped",
+            reason: "No `export default` found; the provider module must default-export its provider.",
+        };
+    }
+    const declaration = call.arguments[0];
+    if (declaration === undefined || !ts.isObjectLiteralExpression(declaration)) {
+        return {
+            status: "skipped",
+            reason: "defineProvider(...) is called with a non-literal argument, so the declaration's operations key cannot be located.",
+        };
+    }
+    const operationsProperty = findOperationsProperty(declaration);
+    // Already migrated: the declaration carries no operations key and the
+    // default export path calls a builder variable rather than defineProvider.
+    if (operationsProperty === undefined &&
+        isAlreadyTwoPhase(source, exportAssignment, call)) {
+        return { status: "unchanged", kind: "two-phase", code: sourceText };
+    }
+    if (operationsProperty === undefined) {
+        return {
+            status: "skipped",
+            reason: "The declaration has no `operations` key and the default export does not call a declaration builder, so the intended shape is ambiguous.",
+        };
+    }
+    const operationsText = operationsPropertyValueText(operationsProperty, source);
+    if (operationsText === undefined) {
+        return {
+            status: "skipped",
+            reason: "The `operations` property uses a form the transform cannot relocate (getter, setter, method, spread, or computed name).",
+        };
+    }
+    const shape = classifyShape(source, call, exportAssignment);
+    if (shape.status === "skipped") {
+        return shape;
+    }
+    const edits = [];
+    const builderName = pickBuilderName(source);
+    // 1. Remove `operations` from the declaration literal.
+    edits.push(...removeOperationsProperty(operationsProperty, declaration, source));
+    // 2. Bind the declaration to `const buildProvider = defineProvider({...})`.
+    edits.push(...introduceBuilder(source, call, shape, builderName));
+    // 3. Route the default export through `buildProvider({ operations })`.
+    edits.push(...rewriteDefaultExport(source, exportAssignment, shape, builderName, operationsText));
+    // 4. `export type ProviderContext = ProviderContextOf<typeof buildProvider>;`
+    //    plus the type-only import, when neither is already present.
+    edits.push(...ensureProviderContextType(source, call, shape, builderName));
+    const code = applyEdits(sourceText, edits);
+    // Re-parse the output: a transform that emits unparseable source is worse
+    // than one that skips, because the pin bump would ship alongside it.
+    const verified = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const outputError = firstSyntaxError(verified);
+    if (outputError !== undefined) {
+        return {
+            status: "skipped",
+            reason: `Transform produced source that does not parse (${outputError}); refusing to emit a partial migration.`,
+        };
+    }
+    return {
+        status: "migrated",
+        kind: shape.kind,
+        code,
+        operationsExpression: operationsText,
+    };
+}
+function classifyShape(source, call, exportAssignment) {
+    const variableStatement = enclosingVariableStatement(call);
+    if (variableStatement === undefined) {
+        // `export default defineProvider({...})`
+        if (exportAssignment.expression === call) {
+            return { status: "ok", kind: "single-phase-default-export" };
+        }
+        return {
+            status: "skipped",
+            reason: "defineProvider(...) is neither bound to a variable nor the default-export expression, so the transform cannot place the builder.",
+        };
+    }
+    const declarations = variableStatement.declarationList.declarations;
+    if (declarations.length !== 1) {
+        return {
+            status: "skipped",
+            reason: "The defineProvider(...) result is declared alongside other bindings in one statement; split the declaration first.",
+        };
+    }
+    const declaration = declarations[0];
+    if (declaration === undefined || !ts.isIdentifier(declaration.name)) {
+        return {
+            status: "skipped",
+            reason: "The defineProvider(...) result is bound to a destructuring pattern.",
+        };
+    }
+    if (declaration.initializer !== call) {
+        return {
+            status: "skipped",
+            reason: "defineProvider(...) is nested inside a larger initializer expression the transform cannot rewrite.",
+        };
+    }
+    const variableName = declaration.name.text;
+    const exported = exportAssignment.expression;
+    if (ts.isIdentifier(exported) && exported.text === variableName) {
+        return {
+            status: "ok",
+            kind: "single-phase-variable-export",
+            variableName,
+            variableStatement,
+        };
+    }
+    if (ts.isObjectLiteralExpression(exported)) {
+        const spreads = exported.properties.filter(ts.isSpreadAssignment);
+        const spreadsProvider = spreads.some((property) => ts.isIdentifier(property.expression) &&
+            property.expression.text === variableName);
+        if (!spreadsProvider) {
+            return {
+                status: "skipped",
+                reason: `The default export is an object literal that does not spread \`${variableName}\`, so the provider value it exports is unclear.`,
+            };
+        }
+        if (spreads.length > 1) {
+            return {
+                status: "skipped",
+                reason: "The default export spreads more than one value; the transform cannot tell which carries the provider.",
+            };
+        }
+        const extras = exported.properties.filter((property) => !ts.isSpreadAssignment(property));
+        return {
+            status: "ok",
+            kind: "single-phase-variable-spread-export",
+            variableName,
+            variableStatement,
+            spreadExportExtras: extras
+                .map((property) => property.getText(source))
+                .join(",\n  "),
+        };
+    }
+    return {
+        status: "skipped",
+        reason: `The default export is neither \`${variableName}\` nor an object literal spreading it.`,
+    };
+}
+function collectDefineProviderCalls(source) {
+    const calls = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === "defineProvider") {
+            calls.push(node);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return calls;
+}
+function findDefaultExport(source) {
+    for (const statement of source.statements) {
+        if (ts.isExportAssignment(statement) && statement.isExportEquals !== true) {
+            return statement;
+        }
+    }
+    return undefined;
+}
+function defaultExportCallsBuilder(exportAssignment, declarationCall) {
+    const expression = exportAssignment.expression;
+    if (!ts.isCallExpression(expression))
+        return false;
+    if (expression === declarationCall)
+        return false;
+    return ts.isIdentifier(expression.expression);
+}
+/**
+ * True when the module is already in the two-phase shape: the default export
+ * resolves to a builder-call result. Covers the three migrated layouts —
+ * `export default buildProvider({...})`, an intermediate
+ * `const provider = buildProvider({...}); export default provider;`, and the
+ * spread export `export default { ...provider, deployment }` over such a
+ * binding. Without the latter two, re-running the transform on its own
+ * spread-shape output reports "ambiguous" instead of "unchanged", which
+ * breaks idempotency for repeated fan-out runs.
+ */
+function isAlreadyTwoPhase(source, exportAssignment, declarationCall) {
+    if (defaultExportCallsBuilder(exportAssignment, declarationCall))
+        return true;
+    const exported = exportAssignment.expression;
+    const candidateNames = [];
+    if (ts.isIdentifier(exported)) {
+        candidateNames.push(exported.text);
+    }
+    else if (ts.isObjectLiteralExpression(exported)) {
+        for (const property of exported.properties) {
+            if (ts.isSpreadAssignment(property) && ts.isIdentifier(property.expression)) {
+                candidateNames.push(property.expression.text);
+            }
+        }
+    }
+    if (candidateNames.length === 0)
+        return false;
+    // Does any spread/exported identifier bind a call to an identifier other
+    // than defineProvider — i.e. a builder call?
+    let found = false;
+    const visit = (node) => {
+        if (found)
+            return;
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            candidateNames.includes(node.name.text) &&
+            node.initializer !== undefined &&
+            ts.isCallExpression(node.initializer) &&
+            node.initializer !== declarationCall &&
+            ts.isIdentifier(node.initializer.expression) &&
+            node.initializer.expression.text !== "defineProvider") {
+            found = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+function findOperationsProperty(declaration) {
+    for (const property of declaration.properties) {
+        if (ts.isSpreadAssignment(property))
+            continue;
+        const name = property.name;
+        if (name === undefined)
+            continue;
+        if ((ts.isIdentifier(name) || ts.isStringLiteral(name)) &&
+            name.text === "operations") {
+            return property;
+        }
+    }
+    return undefined;
+}
+/**
+ * Source text of the value to hand the builder. Shorthand becomes the bare
+ * identifier so `{ operations }` stays idiomatic; a property assignment keeps
+ * its initializer verbatim, including a multi-line inline map.
+ */
+function operationsPropertyValueText(property, source) {
+    if (ts.isShorthandPropertyAssignment(property)) {
+        return property.name.text;
+    }
+    if (ts.isPropertyAssignment(property)) {
+        return property.initializer.getText(source);
+    }
+    return undefined;
+}
+function removeOperationsProperty(property, declaration, source) {
+    const properties = declaration.properties;
+    const index = properties.indexOf(property);
+    const start = property.getFullStart();
+    let end = property.getEnd();
+    // Absorb the trailing comma so the remaining literal stays well-formed,
+    // whether the key sat mid-list or last.
+    const text = source.getFullText();
+    let cursor = end;
+    while (cursor < text.length && /\s/.test(text.charAt(cursor)))
+        cursor += 1;
+    if (text.charAt(cursor) === ",") {
+        end = cursor + 1;
+    }
+    else if (index > 0) {
+        // Last property with no trailing comma: drop the preceding one instead.
+        const previous = properties[index - 1];
+        if (previous !== undefined) {
+            let back = previous.getEnd();
+            while (back < text.length && /\s/.test(text.charAt(back)))
+                back += 1;
+            if (text.charAt(back) === ",") {
+                return [{ start: back, end, text: "" }];
+            }
+        }
+    }
+    return [{ start, end, text: "" }];
+}
+function introduceBuilder(source, call, shape, builderName) {
+    if (shape.kind === "single-phase-default-export") {
+        // `export default defineProvider({...})` becomes a standalone builder
+        // declaration; the default export is re-appended separately.
+        const exportStatement = call.parent;
+        if (!ts.isExportAssignment(exportStatement))
+            return [];
+        return [
+            {
+                start: exportStatement.getStart(source),
+                end: call.getStart(source),
+                text: `const ${builderName} = `,
+            },
+        ];
+    }
+    const statement = shape.variableStatement;
+    if (statement === undefined || shape.variableName === undefined)
+        return [];
+    // Rename the existing binding to the builder name. The old name is
+    // re-introduced for the built provider only in the spread-export shape,
+    // which needs an intermediate value to spread.
+    const declaration = statement.declarationList.declarations[0];
+    if (declaration === undefined || !ts.isIdentifier(declaration.name))
+        return [];
+    return [
+        {
+            start: declaration.name.getStart(source),
+            end: declaration.name.getEnd(),
+            text: builderName,
+        },
+    ];
+}
+function rewriteDefaultExport(source, exportAssignment, shape, builderName, operationsText) {
+    const operationsArgument = operationsText === "operations"
+        ? "{ operations }"
+        : `{ operations: ${operationsText} }`;
+    const call = `${builderName}(${operationsArgument})`;
+    if (shape.kind === "single-phase-default-export") {
+        // The builder declaration replaced the `export default` prefix; the
+        // export itself is appended after what is now the builder statement.
+        return [
+            {
+                start: exportAssignment.getEnd(),
+                end: exportAssignment.getEnd(),
+                text: `\n\nexport default ${call};`,
+            },
+        ];
+    }
+    if (shape.kind === "single-phase-variable-export") {
+        return [
+            {
+                start: exportAssignment.expression.getStart(source),
+                end: exportAssignment.expression.getEnd(),
+                text: call,
+            },
+        ];
+    }
+    // Spread export: re-introduce the provider binding so the extra properties
+    // (currently `deployment`) still spread over a built provider.
+    const providerName = shape.variableName ?? "provider";
+    const extras = shape.spreadExportExtras ?? "";
+    const rebuilt = extras.length > 0
+        ? `{\n  ...${providerName},\n  ${extras},\n}`
+        : `{ ...${providerName} }`;
+    return [
+        {
+            start: exportAssignment.getStart(source),
+            end: exportAssignment.getStart(source),
+            text: `const ${providerName} = ${call};\n\n`,
+        },
+        {
+            start: exportAssignment.expression.getStart(source),
+            end: exportAssignment.expression.getEnd(),
+            text: rebuilt,
+        },
+    ];
+}
+/**
+ * Add `export type ProviderContext = ProviderContextOf<typeof buildProvider>`
+ * and the type-only import when absent. Operation handlers reference this
+ * type, so a migration that omits it leaves the provider without the context
+ * type the two-phase shape exists to provide.
+ */
+function ensureProviderContextType(source, call, shape, builderName) {
+    const text = source.getFullText();
+    const edits = [];
+    const hasContextTypeAlias = source.statements.some((statement) => ts.isTypeAliasDeclaration(statement) &&
+        statement.name.text === PROVIDER_CONTEXT_TYPE_NAME);
+    // A named import of `ProviderContext` (the deprecated SDK-root context
+    // type, imported by legacy sources) occupies the same name: adding the
+    // alias alongside it is TS2440. The import must yield to the derived
+    // alias — the whole point of the two-phase shape — so drop it and let the
+    // alias own the name.
+    const conflictingImportSpecifier = findNamedImportSpecifier(source, PROVIDER_CONTEXT_TYPE_NAME);
+    if (!hasContextTypeAlias) {
+        // After the builder statement — which is the variable statement when the
+        // declaration was bound, or the rewritten export statement otherwise.
+        const anchor = shape.variableStatement ??
+            (ts.isExportAssignment(call.parent) ? call.parent : undefined);
+        if (anchor !== undefined) {
+            const insertAt = anchor.getEnd();
+            edits.push({
+                start: insertAt,
+                end: insertAt,
+                text: `\n\nexport type ${PROVIDER_CONTEXT_TYPE_NAME} = ${PROVIDER_CONTEXT_OF_TYPE_NAME}<typeof ${builderName}>;`,
+            });
+            if (conflictingImportSpecifier !== undefined) {
+                edits.push(removeImportSpecifier(source, conflictingImportSpecifier));
+            }
+        }
+    }
+    if (text.includes(PROVIDER_CONTEXT_OF_TYPE_NAME)) {
+        return edits;
+    }
+    const providerImport = findProviderSdkImport(source);
+    if (providerImport === undefined) {
+        // No named import from the provider subpath to extend; adding a new
+        // import line without knowing the module's style is riskier than
+        // leaving the type import to `bun run check` feedback.
+        return edits;
+    }
+    const named = providerImport.importClause?.namedBindings;
+    if (named === undefined || !ts.isNamedImports(named)) {
+        return edits;
+    }
+    const last = named.elements[named.elements.length - 1];
+    if (last === undefined) {
+        return edits;
+    }
+    edits.push({
+        start: last.getEnd(),
+        end: last.getEnd(),
+        text: `, type ${PROVIDER_CONTEXT_OF_TYPE_NAME}`,
+    });
+    return edits;
+}
+function findProviderSdkImport(source) {
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const moduleSpecifier = statement.moduleSpecifier;
+        if (!ts.isStringLiteral(moduleSpecifier))
+            continue;
+        if (moduleSpecifier.text !== PROVIDER_SDK_PROVIDER_SUBPATH)
+            continue;
+        const named = statement.importClause?.namedBindings;
+        if (named !== undefined && ts.isNamedImports(named)) {
+            const importsDefineProvider = named.elements.some((element) => element.name.text === "defineProvider");
+            if (importsDefineProvider)
+                return statement;
+        }
+    }
+    return undefined;
+}
+/** Named import specifier binding `localName` in any import declaration. */
+function findNamedImportSpecifier(source, localName) {
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const named = statement.importClause?.namedBindings;
+        if (named === undefined || !ts.isNamedImports(named))
+            continue;
+        for (const element of named.elements) {
+            if (element.name.text === localName)
+                return element;
+        }
+    }
+    return undefined;
+}
+/**
+ * Edit removing one specifier from its named-import list, absorbing one
+ * neighboring comma so the list stays well-formed. Callers guarantee the
+ * list has at least one other specifier (legacy sources always import
+ * defineProvider alongside the context type).
+ */
+function removeImportSpecifier(source, specifier) {
+    const list = specifier.parent;
+    const index = list.elements.indexOf(specifier);
+    const text = source.getFullText();
+    let start = specifier.getFullStart();
+    let end = specifier.getEnd();
+    let cursor = end;
+    while (cursor < text.length && /\s/.test(text.charAt(cursor)))
+        cursor += 1;
+    if (text.charAt(cursor) === ",") {
+        end = cursor + 1;
+    }
+    else if (index > 0) {
+        const previous = list.elements[index - 1];
+        if (previous !== undefined) {
+            let back = previous.getEnd();
+            while (back < text.length && /\s/.test(text.charAt(back)))
+                back += 1;
+            if (text.charAt(back) === ",")
+                start = back;
+        }
+    }
+    return { start, end, text: "" };
+}
+/**
+ * `buildProvider` unless the module already binds that name, in which case a
+ * numbered suffix keeps the transform from shadowing an existing binding.
+ */
+function pickBuilderName(source) {
+    const taken = new Set();
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+            taken.add(node.name.text);
+        }
+        if (ts.isFunctionDeclaration(node) && node.name !== undefined) {
+            taken.add(node.name.text);
+        }
+        if (ts.isImportSpecifier(node)) {
+            taken.add(node.name.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (!taken.has(DECLARATION_BUILDER_NAME))
+        return DECLARATION_BUILDER_NAME;
+    for (let suffix = 2; suffix < 100; suffix += 1) {
+        const candidate = `${DECLARATION_BUILDER_NAME}${suffix}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    return `${DECLARATION_BUILDER_NAME}Migrated`;
+}
+function enclosingVariableStatement(node) {
+    let current = node.parent;
+    while (current !== undefined) {
+        if (ts.isVariableStatement(current))
+            return current;
+        if (ts.isSourceFile(current))
+            return undefined;
+        current = current.parent;
+    }
+    return undefined;
+}
+function firstSyntaxError(source) {
+    const diagnostics = source.parseDiagnostics;
+    if (diagnostics === undefined || diagnostics.length === 0)
+        return undefined;
+    const first = diagnostics[0];
+    if (first === undefined)
+        return undefined;
+    const message = ts.flattenDiagnosticMessageText(first.messageText, " ");
+    const { line } = source.getLineAndCharacterOfPosition(first.start);
+    return `${message} (line ${line + 1})`;
+}
+/** Apply edits back-to-front so earlier offsets stay valid. */
+function applyEdits(text, edits) {
+    const ordered = [...edits].sort((a, b) => b.start - a.start || b.end - a.end);
+    let output = text;
+    for (const edit of ordered) {
+        output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+    }
+    return output;
+}

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;