@wp-typia/project-tools 0.19.3 → 0.20.0

package/dist/runtime/typia-llm.d.ts

@@ -0,0 +1,213 @@
+import type { ArtifactSyncExecutionOptions, EndpointManifestDefinition, EndpointManifestEndpointDefinition } from '@wp-typia/block-runtime/metadata-core';
+import type { ILlmFunction, ILlmSchema, ILlmStructuredOutput } from 'typia';
+import { type EndpointAuthIntent, type EndpointWordPressAuthDefinition } from './schema-core.js';
+/**
+ * Method-level descriptor projected from an endpoint manifest for a generated
+ * `typia.llm` controller interface.
+ */
+export interface TypiaLlmEndpointMethodDescriptor {
+    /** Normalized auth intent derived from the endpoint manifest. */
+    authIntent: EndpointAuthIntent;
+    /** Optional auth mode propagated from legacy manifest metadata. */
+    authMode?: EndpointManifestEndpointDefinition['authMode'];
+    /** Human-readable operation summary. */
+    description?: string;
+    /** Input type used by the generated controller method, or null for no input. */
+    inputTypeName: string | null;
+    /** HTTP method from the source endpoint manifest. */
+    method: EndpointManifestEndpointDefinition['method'];
+    /** Stable operation identifier used as the generated method name. */
+    operationId: string;
+    /** Output type used by the generated controller method. */
+    outputTypeName: string;
+    /** REST path from the source endpoint manifest. */
+    path: string;
+    /** Tags copied from the source endpoint manifest. */
+    tags: readonly string[];
+    /** Optional WordPress auth overlay preserved for downstream adapters. */
+    wordpressAuth?: EndpointWordPressAuthDefinition;
+}
+/**
+ * Configures the generated TypeScript module that asks `typia.llm` to derive
+ * function-calling and structured-output artifacts from canonical contracts.
+ */
+export interface RenderTypiaLlmModuleOptions {
+    /** Export name for the generated `typia.llm.application<...>()` value. */
+    applicationExportName: string;
+    /** Generated controller interface name. */
+    interfaceName: string;
+    /** Endpoint manifest that owns REST operation metadata and source type names. */
+    manifest: EndpointManifestDefinition;
+    /** Export name for the generated `typia.llm.structuredOutput<...>()` value. */
+    structuredOutputExportName: string;
+    /** TypeScript output type used for structured-output projection. */
+    structuredOutputTypeName: string;
+    /** Import path from the generated module to the canonical TypeScript contracts. */
+    typesImportPath: string;
+}
+/**
+ * Configures writing or checking the generated `typia.llm` adapter module.
+ */
+export interface SyncTypiaLlmAdapterModuleOptions extends ArtifactSyncExecutionOptions, RenderTypiaLlmModuleOptions {
+    /** Destination path for the generated TypeScript adapter module. */
+    generatedSourceFile: string;
+}
+/**
+ * Describes the generated adapter module and where it was written or checked.
+ */
+export interface SyncTypiaLlmAdapterModuleResult {
+    /** True when the source file was only verified, false when it was written. */
+    check: boolean;
+    /** Generated endpoint method descriptors used by the module renderer. */
+    methodDescriptors: TypiaLlmEndpointMethodDescriptor[];
+    /** Rendered TypeScript module source. */
+    source: string;
+    /** Destination path for the generated TypeScript adapter module. */
+    sourceFile: string;
+}
+/**
+ * Function schema shape projected from a compiled `typia.llm.application(...)`
+ * result.
+ */
+export interface TypiaLlmFunctionLike extends Pick<ILlmFunction, 'description' | 'name' | 'output' | 'parameters'> {
+    /** Function description generated by `typia.llm`. */
+    description?: string;
+    /** Function name generated by `typia.llm`. */
+    name: string;
+    /** Optional output schema generated by `typia.llm`. */
+    output?: ILlmSchema.IParameters;
+    /** Function parameter schema generated by `typia.llm`. */
+    parameters: ILlmSchema.IParameters;
+    /** Optional tags generated by `typia.llm`. */
+    tags?: readonly string[];
+}
+/**
+ * Application shape projected from a compiled `typia.llm.application(...)`
+ * result.
+ */
+export interface TypiaLlmApplicationLike {
+    /** Function schemas generated by `typia.llm`. */
+    functions: readonly TypiaLlmFunctionLike[];
+}
+/**
+ * Structured-output shape projected from a compiled
+ * `typia.llm.structuredOutput(...)` result.
+ */
+export interface TypiaLlmStructuredOutputLike extends Pick<ILlmStructuredOutput, 'parameters'> {
+    /** Structured output parameters generated by `typia.llm`. */
+    parameters: ILlmStructuredOutput['parameters'];
+}
+/**
+ * JSON-friendly function artifact for downstream adapter consumers.
+ */
+export interface ProjectedTypiaLlmFunctionArtifact {
+    /** Function description generated by `typia.llm`. */
+    description?: string;
+    /** Function name generated by `typia.llm`. */
+    name: string;
+    /** Optional output schema generated by `typia.llm`. */
+    output?: ILlmSchema.IParameters;
+    /** Function parameter schema generated by `typia.llm`. */
+    parameters: ILlmSchema.IParameters;
+    /** Optional tags generated by `typia.llm`. */
+    tags?: string[];
+}
+/**
+ * JSON-friendly application artifact for downstream adapter consumers.
+ */
+export interface ProjectedTypiaLlmApplicationArtifact {
+    /** Function-calling artifacts generated by `typia.llm`. */
+    functions: ProjectedTypiaLlmFunctionArtifact[];
+    /** Source metadata that keeps the artifact tied to canonical contracts. */
+    generatedFrom: {
+        baselineOpenApiPath?: string;
+        blockSlug: string;
+        manifestSource: 'endpoint-manifest+typescript';
+    };
+}
+/**
+ * JSON-friendly structured-output artifact for downstream adapter consumers.
+ */
+export interface ProjectedTypiaLlmStructuredOutputArtifact {
+    /** Source metadata that keeps the artifact tied to canonical contracts. */
+    generatedFrom: {
+        aiSchemaPath?: string;
+        blockSlug: string;
+        outputTypeName: string;
+    };
+    /** Structured output parameters generated by `typia.llm`. */
+    parameters: ILlmStructuredOutput['parameters'];
+}
+/**
+ * Configures projection of a compiled `typia.llm.application(...)` result into
+ * the JSON-friendly adapter artifact.
+ */
+export interface ProjectTypiaLlmApplicationArtifactOptions {
+    /** Compiled application value produced by `typia.llm.application(...)`. */
+    application: TypiaLlmApplicationLike;
+    /** Source metadata for the generated JSON artifact. */
+    generatedFrom: ProjectedTypiaLlmApplicationArtifact['generatedFrom'];
+    /** Optional hook for adapter-specific function schema normalization. */
+    transformFunction?: (functionArtifact: ProjectedTypiaLlmFunctionArtifact, functionSchema: TypiaLlmFunctionLike) => ProjectedTypiaLlmFunctionArtifact;
+}
+/**
+ * Configures projection of a compiled `typia.llm.structuredOutput(...)` result
+ * into the JSON-friendly adapter artifact.
+ */
+export interface ProjectTypiaLlmStructuredOutputArtifactOptions {
+    /** Source metadata for the generated JSON artifact. */
+    generatedFrom: ProjectedTypiaLlmStructuredOutputArtifact['generatedFrom'];
+    /** Compiled structured-output value produced by `typia.llm.structuredOutput(...)`. */
+    structuredOutput: TypiaLlmStructuredOutputLike;
+}
+/**
+ * Builds the generated controller method descriptors that bridge endpoint
+ * manifests to `typia.llm` TypeScript interfaces.
+ *
+ * @param manifest Endpoint manifest that owns operation and source type names.
+ * @returns Ordered method descriptors matching the manifest endpoints.
+ * @throws When an endpoint has ambiguous query/body input mapping.
+ * @throws When an endpoint references a missing input or output contract.
+ */
+export declare function buildTypiaLlmEndpointMethodDescriptors(manifest: EndpointManifestDefinition): TypiaLlmEndpointMethodDescriptor[];
+/**
+ * Renders a build-time-only TypeScript module that invokes `typia.llm` against
+ * canonical manifest-owned contracts.
+ *
+ * @param options Render options for the generated adapter module.
+ * @returns The generated TypeScript source.
+ */
+export declare function renderTypiaLlmModule({ applicationExportName, interfaceName, manifest, structuredOutputExportName, structuredOutputTypeName, typesImportPath, }: RenderTypiaLlmModuleOptions): string;
+/**
+ * Writes or verifies the generated build-time `typia.llm` adapter module. The
+ * returned TypeScript source still needs to be compiled by the consuming
+ * project's Typia transformer before JSON artifacts can be read from it.
+ *
+ * @param options Generated module destination plus render options.
+ * @returns Rendered source, method descriptors, and the checked/written file path.
+ */
+export declare function syncTypiaLlmAdapterModule({ check, generatedSourceFile, ...renderOptions }: SyncTypiaLlmAdapterModuleOptions): Promise<SyncTypiaLlmAdapterModuleResult>;
+/**
+ * Projects one compiled `typia.llm` function schema into a JSON-friendly
+ * artifact record.
+ *
+ * @param functionSchema Function schema from a compiled `typia.llm.application(...)`.
+ * @returns JSON-friendly function artifact.
+ */
+export declare function projectTypiaLlmApplicationFunction(functionSchema: TypiaLlmFunctionLike): ProjectedTypiaLlmFunctionArtifact;
+/**
+ * Projects a compiled `typia.llm.application(...)` result into a JSON-friendly
+ * downstream adapter artifact.
+ *
+ * @param options Compiled application value and source metadata.
+ * @returns JSON-friendly application artifact.
+ */
+export declare function projectTypiaLlmApplicationArtifact({ application, generatedFrom, transformFunction, }: ProjectTypiaLlmApplicationArtifactOptions): ProjectedTypiaLlmApplicationArtifact;
+/**
+ * Projects a compiled `typia.llm.structuredOutput(...)` result into a
+ * JSON-friendly downstream adapter artifact.
+ *
+ * @param options Compiled structured-output value and source metadata.
+ * @returns JSON-friendly structured-output artifact.
+ */
+export declare function projectTypiaLlmStructuredOutputArtifact({ generatedFrom, structuredOutput, }: ProjectTypiaLlmStructuredOutputArtifactOptions): ProjectedTypiaLlmStructuredOutputArtifact;

package/dist/runtime/typia-llm.js

@@ -0,0 +1,348 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { cloneJsonValue } from './json-utils.js';
+import { normalizeEndpointAuthDefinition, } from './schema-core.js';
+const TYPESCRIPT_RESERVED_WORDS = new Set([
+    'abstract',
+    'any',
+    'as',
+    'asserts',
+    'async',
+    'await',
+    'bigint',
+    'boolean',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'constructor',
+    'continue',
+    'debugger',
+    'declare',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'from',
+    'function',
+    'get',
+    'global',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'infer',
+    'instanceof',
+    'interface',
+    'is',
+    'keyof',
+    'let',
+    'module',
+    'namespace',
+    'never',
+    'new',
+    'null',
+    'number',
+    'object',
+    'of',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'readonly',
+    'require',
+    'return',
+    'satisfies',
+    'set',
+    'static',
+    'string',
+    'super',
+    'switch',
+    'symbol',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'type',
+    'typeof',
+    'undefined',
+    'unique',
+    'unknown',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+function cloneJsonValueIfDefined(value) {
+    return value === undefined ? undefined : cloneJsonValue(value);
+}
+function getEndpointInputTypeName(manifest, endpoint) {
+    if (endpoint.bodyContract && endpoint.queryContract) {
+        throw new Error(`Endpoint "${endpoint.operationId}" defines both bodyContract and queryContract; typia.llm input mapping is ambiguous.`);
+    }
+    const contractName = endpoint.method === 'GET'
+        ? endpoint.queryContract ?? null
+        : endpoint.bodyContract ?? endpoint.queryContract ?? null;
+    if (!contractName) {
+        return null;
+    }
+    const contract = manifest.contracts[contractName];
+    if (!contract) {
+        throw new Error(`Endpoint "${endpoint.operationId}" references missing input contract "${contractName}".`);
+    }
+    return contract.sourceTypeName;
+}
+function getEndpointOutputTypeName(manifest, endpoint) {
+    const contract = manifest.contracts[endpoint.responseContract];
+    if (!contract) {
+        throw new Error(`Endpoint "${endpoint.operationId}" references missing response contract "${endpoint.responseContract}".`);
+    }
+    return contract.sourceTypeName;
+}
+function escapeJsDocLine(line) {
+    return line.replace(/\*\//g, '* /');
+}
+function normalizeGeneratedArtifactContent(content) {
+    return content.replace(/\r\n?/g, '\n');
+}
+function renderDescriptionJsDocLines(method) {
+    const description = method.description && method.description.trim().length > 0
+        ? method.description
+        : method.operationId;
+    const descriptionLines = description
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => line.trim().replace(/\s+/g, ' '))
+        .filter(Boolean);
+    return (descriptionLines.length > 0
+        ? descriptionLines
+        : [method.operationId]).map((line) => ` * ${escapeJsDocLine(line)}`);
+}
+function renderMethodJsDoc(method) {
+    const lines = [
+        '/**',
+        ...renderDescriptionJsDocLines(method),
+        ' *',
+        ` * REST path: ${method.method} ${method.path}`,
+        ` * Auth intent: ${method.authIntent}`,
+        ...(method.wordpressAuth
+            ? [
+                ` * WordPress auth: ${method.wordpressAuth.mechanism}${method.wordpressAuth.publicTokenField
+                    ? ` (field: ${method.wordpressAuth.publicTokenField})`
+                    : ''}`,
+            ]
+            : []),
+        ...method.tags.map((tag) => ` * @tag ${escapeJsDocLine(tag)}`),
+        ' */',
+    ];
+    return lines.join('\n');
+}
+function renderMethodSignature(method) {
+    const inputSignature = method.inputTypeName === null ? '' : `input: ${method.inputTypeName}`;
+    const methodName = /^[$A-Z_][$0-9A-Z_]*$/i.test(method.operationId) &&
+        !TYPESCRIPT_RESERVED_WORDS.has(method.operationId)
+        ? method.operationId
+        : JSON.stringify(method.operationId);
+    return `${methodName}(${inputSignature}): ${method.outputTypeName};`;
+}
+function renderTypiaLlmModuleFromMethodDescriptors({ applicationExportName, interfaceName, structuredOutputExportName, structuredOutputTypeName, typesImportPath, }, methods) {
+    const importedTypeNames = new Set([structuredOutputTypeName]);
+    for (const method of methods) {
+        importedTypeNames.add(method.outputTypeName);
+        if (method.inputTypeName) {
+            importedTypeNames.add(method.inputTypeName);
+        }
+    }
+    const imports = Array.from(importedTypeNames).sort().join(',\n\t');
+    const methodBlocks = methods
+        .map((method) => {
+        const jsDoc = renderMethodJsDoc(method)
+            .split('\n')
+            .map((line) => `\t${line}`)
+            .join('\n');
+        return `${jsDoc}\n\t${renderMethodSignature(method)}`;
+    })
+        .join('\n\n');
+    return `import typia from "typia";
+import type {
+\t${imports},
+} from "${typesImportPath}";
+
+export interface ${interfaceName} {
+${methodBlocks}
+}
+
+export const ${applicationExportName} =
+\ttypia.llm.application<${interfaceName}>();
+
+export const ${structuredOutputExportName} =
+\ttypia.llm.structuredOutput<${structuredOutputTypeName}>();
+`;
+}
+async function reconcileGeneratedTypiaLlmArtifacts(artifacts, check) {
+    if (!check) {
+        for (const artifact of artifacts) {
+            await mkdir(path.dirname(artifact.filePath), {
+                recursive: true,
+            });
+            await writeFile(artifact.filePath, artifact.content, 'utf8');
+        }
+        return;
+    }
+    const issues = [];
+    for (const artifact of artifacts) {
+        try {
+            const current = normalizeGeneratedArtifactContent(await readFile(artifact.filePath, 'utf8'));
+            const expected = normalizeGeneratedArtifactContent(artifact.content);
+            if (current !== expected) {
+                issues.push(`- ${artifact.filePath} (stale)`);
+            }
+        }
+        catch (error) {
+            const code = error && typeof error === 'object' && 'code' in error
+                ? error.code
+                : undefined;
+            if (code === 'ENOENT') {
+                issues.push(`- ${artifact.filePath} (missing)`);
+                continue;
+            }
+            issues.push(`- ${artifact.filePath} (unreadable: ${error instanceof Error ? error.message : code ?? 'unknown'})`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new Error(`Generated typia.llm artifacts are missing or stale:\n${issues.join('\n')}`);
+    }
+}
+/**
+ * Builds the generated controller method descriptors that bridge endpoint
+ * manifests to `typia.llm` TypeScript interfaces.
+ *
+ * @param manifest Endpoint manifest that owns operation and source type names.
+ * @returns Ordered method descriptors matching the manifest endpoints.
+ * @throws When an endpoint has ambiguous query/body input mapping.
+ * @throws When an endpoint references a missing input or output contract.
+ */
+export function buildTypiaLlmEndpointMethodDescriptors(manifest) {
+    return manifest.endpoints.map((endpoint) => {
+        const normalizedAuth = normalizeEndpointAuthDefinition(endpoint);
+        return {
+            authIntent: normalizedAuth.auth,
+            ...(normalizedAuth.authMode ? { authMode: normalizedAuth.authMode } : {}),
+            description: endpoint.summary,
+            inputTypeName: getEndpointInputTypeName(manifest, endpoint),
+            method: endpoint.method,
+            operationId: endpoint.operationId,
+            outputTypeName: getEndpointOutputTypeName(manifest, endpoint),
+            path: endpoint.path,
+            tags: endpoint.tags ?? [],
+            ...(normalizedAuth.wordpressAuth
+                ? { wordpressAuth: normalizedAuth.wordpressAuth }
+                : {}),
+        };
+    });
+}
+/**
+ * Renders a build-time-only TypeScript module that invokes `typia.llm` against
+ * canonical manifest-owned contracts.
+ *
+ * @param options Render options for the generated adapter module.
+ * @returns The generated TypeScript source.
+ */
+export function renderTypiaLlmModule({ applicationExportName, interfaceName, manifest, structuredOutputExportName, structuredOutputTypeName, typesImportPath, }) {
+    return renderTypiaLlmModuleFromMethodDescriptors({
+        applicationExportName,
+        interfaceName,
+        structuredOutputExportName,
+        structuredOutputTypeName,
+        typesImportPath,
+    }, buildTypiaLlmEndpointMethodDescriptors(manifest));
+}
+/**
+ * Writes or verifies the generated build-time `typia.llm` adapter module. The
+ * returned TypeScript source still needs to be compiled by the consuming
+ * project's Typia transformer before JSON artifacts can be read from it.
+ *
+ * @param options Generated module destination plus render options.
+ * @returns Rendered source, method descriptors, and the checked/written file path.
+ */
+export async function syncTypiaLlmAdapterModule({ check = false, generatedSourceFile, ...renderOptions }) {
+    const methodDescriptors = buildTypiaLlmEndpointMethodDescriptors(renderOptions.manifest);
+    const source = renderTypiaLlmModuleFromMethodDescriptors(renderOptions, methodDescriptors);
+    await reconcileGeneratedTypiaLlmArtifacts([
+        {
+            content: source,
+            filePath: generatedSourceFile,
+        },
+    ], check);
+    return {
+        check,
+        methodDescriptors,
+        source,
+        sourceFile: generatedSourceFile,
+    };
+}
+/**
+ * Projects one compiled `typia.llm` function schema into a JSON-friendly
+ * artifact record.
+ *
+ * @param functionSchema Function schema from a compiled `typia.llm.application(...)`.
+ * @returns JSON-friendly function artifact.
+ */
+export function projectTypiaLlmApplicationFunction(functionSchema) {
+    return {
+        description: functionSchema.description,
+        name: functionSchema.name,
+        output: cloneJsonValueIfDefined(functionSchema.output),
+        parameters: cloneJsonValue(functionSchema.parameters),
+        ...(functionSchema.tags ? { tags: [...functionSchema.tags] } : {}),
+    };
+}
+function cloneProjectedTypiaLlmFunctionArtifact(functionArtifact) {
+    return {
+        description: functionArtifact.description,
+        name: functionArtifact.name,
+        output: cloneJsonValueIfDefined(functionArtifact.output),
+        parameters: cloneJsonValue(functionArtifact.parameters),
+        ...(functionArtifact.tags ? { tags: [...functionArtifact.tags] } : {}),
+    };
+}
+/**
+ * Projects a compiled `typia.llm.application(...)` result into a JSON-friendly
+ * downstream adapter artifact.
+ *
+ * @param options Compiled application value and source metadata.
+ * @returns JSON-friendly application artifact.
+ */
+export function projectTypiaLlmApplicationArtifact({ application, generatedFrom, transformFunction, }) {
+    return {
+        functions: application.functions.map((functionSchema) => {
+            const functionArtifact = projectTypiaLlmApplicationFunction(functionSchema);
+            const transformedArtifact = transformFunction
+                ? transformFunction(functionArtifact, functionSchema)
+                : functionArtifact;
+            return cloneProjectedTypiaLlmFunctionArtifact(transformedArtifact);
+        }),
+        generatedFrom: cloneJsonValue(generatedFrom),
+    };
+}
+/**
+ * Projects a compiled `typia.llm.structuredOutput(...)` result into a
+ * JSON-friendly downstream adapter artifact.
+ *
+ * @param options Compiled structured-output value and source metadata.
+ * @returns JSON-friendly structured-output artifact.
+ */
+export function projectTypiaLlmStructuredOutputArtifact({ generatedFrom, structuredOutput, }) {
+    return {
+        generatedFrom: cloneJsonValue(generatedFrom),
+        parameters: cloneJsonValue(structuredOutput.parameters),
+    };
+}

package/dist/runtime/wordpress-ai.d.ts

@@ -0,0 +1,122 @@
+import type { EndpointManifestDefinition, EndpointManifestEndpointDefinition } from '@wp-typia/block-runtime/metadata-core';
+import { type EndpointAuthIntent, type EndpointWordPressAuthDefinition, type JsonSchemaDocument } from './schema-core.js';
+import { type AbilitySpecCatalog } from './ability-spec.js';
+export type { AbilityAnnotationSpec, AbilityCategorySpec, AbilityMcpProjectionSpec, AbilityMetaSpec, AbilitySpec, AbilitySpecCatalog, } from './ability-spec.js';
+/**
+ * Represents one projected WordPress-native ability derived from an endpoint
+ * manifest plus an AbilitySpec definition.
+ */
+export interface ProjectedWordPressAbilityDefinition {
+    /** Normalized auth intent derived from the endpoint manifest. */
+    authIntent: EndpointAuthIntent;
+    /** Optional auth mode propagated from the manifest when present. */
+    authMode?: EndpointManifestEndpointDefinition['authMode'];
+    /** Shared category identifier resolved from the AbilitySpec catalog. */
+    category: string;
+    /** Human-readable summary shown to ability discovery consumers. */
+    description: string;
+    /** PHP callback that executes the ability. */
+    executeCallback: string;
+    /** Stable generated ability identifier. */
+    id: string;
+    /** Optional projected input schema, or null when no input exists. */
+    inputSchema: Record<string, unknown> | null;
+    /** Display label propagated from the AbilitySpec layer. */
+    label: string;
+    /** WordPress-owned metadata preserved in the projected document. */
+    meta: Record<string, unknown>;
+    /** HTTP method from the source endpoint manifest. */
+    method: EndpointManifestEndpointDefinition['method'];
+    /** Source operation identifier from the endpoint manifest. */
+    operationId: string;
+    /** Projected AI response schema shared by the document. */
+    outputSchema: Record<string, unknown>;
+    /** HTTP path from the source endpoint manifest. */
+    path: string;
+    /** PHP permission callback that gates the ability. */
+    permissionCallback: string;
+    /** Optional WordPress auth metadata preserved for downstream adapters. */
+    wordpressAuth?: EndpointWordPressAuthDefinition;
+}
+/**
+ * Bundles a single-category WordPress AI abilities document together with the
+ * metadata that describes how it was generated.
+ */
+export interface ProjectedWordPressAbilitiesDocument {
+    /** Ability definitions generated from the current manifest and AbilitySpec map. */
+    abilities: ProjectedWordPressAbilityDefinition[];
+    /** Shared category metadata for the generated document. */
+    category: {
+        id: string;
+        label: string;
+    };
+    /** Source metadata that points downstream consumers at the generated schema. */
+    generatedFrom: {
+        blockSlug: string;
+        responseSchemaPath: string;
+        schemaProfile: 'ai-structured-output';
+    };
+}
+/**
+ * Carries the projected input schema plus endpoint metadata into an optional
+ * transform hook.
+ */
+export interface WordPressAiInputSchemaTransformContext {
+    /** Name of the input contract being transformed. */
+    contractName: string;
+    /** Source endpoint that requested the input schema. */
+    endpoint: EndpointManifestEndpointDefinition;
+    /** Already-projected AI-friendly input schema. */
+    schema: JsonSchemaDocument & Record<string, unknown>;
+}
+interface BuildWordPressAbilitiesDocumentOptions {
+    abilityCatalog: AbilitySpecCatalog;
+    buildAbilityId?: (operationId: string) => string;
+    generatedFrom: ProjectedWordPressAbilitiesDocument['generatedFrom'];
+    loadInputSchema?: (endpoint: EndpointManifestEndpointDefinition, contractName: string) => Promise<JsonSchemaDocument & Record<string, unknown>>;
+    manifest: EndpointManifestDefinition;
+    outputSchema: Record<string, unknown>;
+    transformInputSchema?: (context: WordPressAiInputSchemaTransformContext) => JsonSchemaDocument & Record<string, unknown>;
+}
+interface BuildWordPressAiArtifactsOptions extends Omit<BuildWordPressAbilitiesDocumentOptions, 'outputSchema'> {
+    responseSchema: JsonSchemaDocument & Record<string, unknown>;
+}
+/**
+ * Projects a canonical schema into the AI structured-output profile used by
+ * WordPress AI artifact generation.
+ *
+ * @param schema Canonical JSON Schema document from the manifest-owned source.
+ * @returns The projected AI-friendly schema document.
+ */
+export declare function projectWordPressAiSchema(schema: JsonSchemaDocument & Record<string, unknown>): JsonSchemaDocument & Record<string, unknown>;
+/**
+ * Builds a WordPress abilities document from a manifest-first REST surface and
+ * a matching AbilitySpec catalog.
+ *
+ * Input schemas are loaded lazily per endpoint only when an input contract
+ * exists, and `transformInputSchema` runs after the schema has already been
+ * projected into the AI structured-output profile.
+ *
+ * @param options Manifest, ability catalog, and projected output schema inputs.
+ * @returns The generated WordPress abilities document.
+ * @throws When an endpoint is missing an AbilitySpec.
+ * @throws When categories are missing, inconsistent, or span multiple documents.
+ * @throws When an endpoint references a missing input contract or no loader was supplied.
+ */
+export declare function buildWordPressAbilitiesDocument({ abilityCatalog, buildAbilityId, generatedFrom, loadInputSchema, manifest, outputSchema, transformInputSchema, }: BuildWordPressAbilitiesDocumentOptions): Promise<ProjectedWordPressAbilitiesDocument>;
+/**
+ * Builds the projected AI response schema together with its companion
+ * WordPress abilities document.
+ *
+ * All endpoints must share the same response contract and category so the
+ * generated artifacts stay aligned with one manifest-owned response surface.
+ *
+ * @param options Manifest, ability catalog, and response schema inputs.
+ * @returns The projected AI response schema and generated abilities document.
+ * @throws When the manifest has no endpoints.
+ * @throws When the shared response contract is missing or inconsistent.
+ */
+export declare function buildWordPressAiArtifacts({ abilityCatalog, buildAbilityId, generatedFrom, loadInputSchema, manifest, responseSchema, transformInputSchema, }: BuildWordPressAiArtifactsOptions): Promise<{
+    abilitiesDocument: ProjectedWordPressAbilitiesDocument;
+    aiResponseSchema: Record<string, unknown>;
+}>;