@wp-typia/project-tools 0.11.1

package/dist/runtime/schema-core.js

@@ -0,0 +1,597 @@
+const WP_TYPIA_OPENAPI_EXTENSION_KEYS = {
+    AUTH_INTENT: "x-typia-authIntent",
+    AUTH_POLICY: "x-wp-typia-authPolicy",
+    PUBLIC_TOKEN_FIELD: "x-wp-typia-publicTokenField",
+    TYPE_TAG: "x-typeTag",
+};
+const WP_TYPIA_OPENAPI_LITERALS = {
+    JSON_CONTENT_TYPE: "application/json",
+    PUBLIC_WRITE_TOKEN_FIELD: "publicWriteToken",
+    QUERY_LOCATION: "query",
+    SUCCESS_RESPONSE_DESCRIPTION: "Successful response",
+    WORDPRESS_PUBLIC_TOKEN_MECHANISM: "public-signed-token",
+    WORDPRESS_REST_NONCE_MECHANISM: "rest-nonce",
+    WP_REST_NONCE_HEADER: "X-WP-Nonce",
+    WP_REST_NONCE_SCHEME: "wpRestNonce",
+};
+const WP_TYPIA_SCHEMA_UINT32_MAX = 4294967295;
+const WP_TYPIA_SCHEMA_INT32_MAX = 2147483647;
+const WP_TYPIA_SCHEMA_INT32_MIN = -2147483648;
+function applyConstraintIfNumber(schema, key, value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        schema[key] = value;
+    }
+}
+function applyConstraintIfString(schema, key, value) {
+    if (typeof value === "string" && value.length > 0) {
+        schema[key] = value;
+    }
+}
+function applyCommonConstraints(schema, constraints) {
+    applyConstraintIfString(schema, "format", constraints.format);
+    applyConstraintIfString(schema, "pattern", constraints.pattern);
+    applyConstraintIfString(schema, WP_TYPIA_OPENAPI_EXTENSION_KEYS.TYPE_TAG, constraints.typeTag);
+    applyConstraintIfNumber(schema, "minLength", constraints.minLength);
+    applyConstraintIfNumber(schema, "maxLength", constraints.maxLength);
+    applyConstraintIfNumber(schema, "minimum", constraints.minimum);
+    applyConstraintIfNumber(schema, "maximum", constraints.maximum);
+    applyConstraintIfNumber(schema, "exclusiveMinimum", constraints.exclusiveMinimum);
+    applyConstraintIfNumber(schema, "exclusiveMaximum", constraints.exclusiveMaximum);
+    applyConstraintIfNumber(schema, "multipleOf", constraints.multipleOf);
+    applyConstraintIfNumber(schema, "minItems", constraints.minItems);
+    applyConstraintIfNumber(schema, "maxItems", constraints.maxItems);
+}
+function createUnionDiscriminatorProperty(branchKey) {
+    return {
+        const: branchKey,
+        enum: [branchKey],
+        type: "string",
+    };
+}
+function addDiscriminatorToObjectBranch(schema, discriminator, branchKey) {
+    if (typeof schema.properties !== "object" ||
+        schema.properties === null ||
+        Array.isArray(schema.properties)) {
+        return null;
+    }
+    const properties = schema.properties;
+    properties[discriminator] = createUnionDiscriminatorProperty(branchKey);
+    const required = Array.isArray(schema.required)
+        ? [...new Set([...schema.required, discriminator])]
+        : [discriminator];
+    schema.required = required;
+    return schema;
+}
+function isJsonSchemaObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function cloneJsonSchemaNode(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => isJsonSchemaObject(item) || Array.isArray(item)
+            ? cloneJsonSchemaNode(item)
+            : item);
+    }
+    if (!isJsonSchemaObject(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+        key,
+        child === undefined
+            ? undefined
+            : isJsonSchemaObject(child) || Array.isArray(child)
+                ? cloneJsonSchemaNode(child)
+                : child,
+    ]));
+}
+function isWpTypiaSchemaExtensionKey(key) {
+    return key.startsWith("x-wp-typia-");
+}
+function getProjectedNumericMultipleOf(schema, path, typeTag) {
+    const currentMultipleOf = schema.multipleOf;
+    if (currentMultipleOf !== undefined &&
+        (typeof currentMultipleOf !== "number" ||
+            !Number.isFinite(currentMultipleOf) ||
+            !Number.isInteger(currentMultipleOf) ||
+            currentMultipleOf <= 0)) {
+        throw new Error(`Unable to project unsupported ${typeTag} multipleOf at "${path}".`);
+    }
+    return typeof currentMultipleOf === "number" ? currentMultipleOf : 1;
+}
+function applyProjectedUint32Constraints(schema, path) {
+    const currentMinimum = schema.minimum;
+    if (typeof currentMinimum === "number" && Number.isFinite(currentMinimum)) {
+        schema.minimum = Math.max(currentMinimum, 0);
+    }
+    else {
+        schema.minimum = 0;
+    }
+    const currentMaximum = schema.maximum;
+    if (typeof currentMaximum === "number" && Number.isFinite(currentMaximum)) {
+        schema.maximum = Math.min(currentMaximum, WP_TYPIA_SCHEMA_UINT32_MAX);
+    }
+    else {
+        schema.maximum = WP_TYPIA_SCHEMA_UINT32_MAX;
+    }
+    schema.multipleOf = getProjectedNumericMultipleOf(schema, path, "uint32");
+    schema.type = "integer";
+}
+function applyProjectedInt32Constraints(schema, path) {
+    const currentMinimum = schema.minimum;
+    if (typeof currentMinimum === "number" && Number.isFinite(currentMinimum)) {
+        schema.minimum = Math.max(currentMinimum, WP_TYPIA_SCHEMA_INT32_MIN);
+    }
+    else {
+        schema.minimum = WP_TYPIA_SCHEMA_INT32_MIN;
+    }
+    const currentMaximum = schema.maximum;
+    if (typeof currentMaximum === "number" && Number.isFinite(currentMaximum)) {
+        schema.maximum = Math.min(currentMaximum, WP_TYPIA_SCHEMA_INT32_MAX);
+    }
+    else {
+        schema.maximum = WP_TYPIA_SCHEMA_INT32_MAX;
+    }
+    schema.multipleOf = getProjectedNumericMultipleOf(schema, path, "int32");
+    schema.type = "integer";
+}
+function applyProjectedTypeTag(schema, typeTag, path) {
+    switch (typeTag) {
+        case "uint32":
+            applyProjectedUint32Constraints(schema, path);
+            break;
+        case "int32":
+            applyProjectedInt32Constraints(schema, path);
+            break;
+        case "float":
+        case "double":
+            schema.type = "number";
+            break;
+        default:
+            throw new Error(`Unsupported wp-typia schema type tag "${typeTag}" at "${path}".`);
+    }
+}
+function projectSchemaArrayItemsForAiStructuredOutput(items, path) {
+    return items.map((item, index) => projectSchemaObjectForAiStructuredOutput(item, `${path}/${index}`));
+}
+function projectSchemaPropertyMapForAiStructuredOutput(properties, path) {
+    return Object.fromEntries(Object.entries(properties).map(([key, value]) => [
+        key,
+        projectSchemaObjectForAiStructuredOutput(value, `${path}/${key}`),
+    ]));
+}
+function projectSchemaObjectForAiStructuredOutput(node, path) {
+    const projectedNode = cloneJsonSchemaNode(node);
+    const rawTypeTag = projectedNode[WP_TYPIA_OPENAPI_EXTENSION_KEYS.TYPE_TAG];
+    if (typeof rawTypeTag === "string") {
+        applyProjectedTypeTag(projectedNode, rawTypeTag, path);
+    }
+    delete projectedNode[WP_TYPIA_OPENAPI_EXTENSION_KEYS.TYPE_TAG];
+    for (const key of Object.keys(projectedNode)) {
+        if (isWpTypiaSchemaExtensionKey(key)) {
+            delete projectedNode[key];
+            continue;
+        }
+        const child = projectedNode[key];
+        if (Array.isArray(child)) {
+            projectedNode[key] = child.every(isJsonSchemaObject)
+                ? projectSchemaArrayItemsForAiStructuredOutput(child, `${path}/${key}`)
+                : child;
+            continue;
+        }
+        if (!isJsonSchemaObject(child)) {
+            continue;
+        }
+        if (key === "properties") {
+            projectedNode[key] = projectSchemaPropertyMapForAiStructuredOutput(child, `${path}/${key}`);
+            continue;
+        }
+        projectedNode[key] = projectSchemaObjectForAiStructuredOutput(child, `${path}/${key}`);
+    }
+    return projectedNode;
+}
+function manifestUnionToJsonSchema(union) {
+    const oneOf = Object.entries(union.branches).map(([branchKey, branch]) => {
+        if (branch.ts.kind !== "object") {
+            throw new Error(`Discriminated union branch "${branchKey}" must be an object to carry "${union.discriminator}".`);
+        }
+        const schema = manifestAttributeToJsonSchema(branch);
+        const objectSchema = addDiscriminatorToObjectBranch(schema, union.discriminator, branchKey);
+        if (!objectSchema) {
+            throw new Error(`Discriminated union branch "${branchKey}" is missing an object schema for "${union.discriminator}".`);
+        }
+        return objectSchema;
+    });
+    return {
+        discriminator: {
+            propertyName: union.discriminator,
+        },
+        oneOf,
+    };
+}
+/**
+ * Converts one manifest attribute definition into a JSON Schema fragment.
+ *
+ * @param attribute Manifest-derived attribute metadata.
+ * @returns A JSON-compatible schema fragment for the attribute.
+ */
+export function manifestAttributeToJsonSchema(attribute) {
+    if (attribute.ts.union) {
+        const schema = manifestUnionToJsonSchema(attribute.ts.union);
+        if (attribute.typia.hasDefault) {
+            schema.default = attribute.typia.defaultValue ?? null;
+        }
+        return schema;
+    }
+    const schema = {};
+    const enumValues = Array.isArray(attribute.wp.enum) ? attribute.wp.enum : null;
+    if (enumValues && enumValues.length > 0) {
+        schema.enum = enumValues;
+    }
+    if (attribute.typia.hasDefault) {
+        schema.default = attribute.typia.defaultValue ?? null;
+    }
+    switch (attribute.ts.kind) {
+        case "string":
+            schema.type = "string";
+            break;
+        case "number":
+            schema.type = "number";
+            break;
+        case "boolean":
+            schema.type = "boolean";
+            break;
+        case "array":
+            schema.type = "array";
+            if (attribute.ts.items) {
+                schema.items = manifestAttributeToJsonSchema(attribute.ts.items);
+            }
+            break;
+        case "object": {
+            schema.type = "object";
+            schema.additionalProperties = false;
+            const properties = attribute.ts.properties ?? {};
+            schema.properties = Object.fromEntries(Object.entries(properties).map(([key, value]) => [
+                key,
+                manifestAttributeToJsonSchema(value),
+            ]));
+            const required = Object.entries(properties)
+                .filter(([, value]) => value.ts.required !== false)
+                .map(([key]) => key);
+            if (required.length > 0) {
+                schema.required = required;
+            }
+            break;
+        }
+        case "union":
+            if (attribute.ts.union) {
+                return manifestUnionToJsonSchema(attribute.ts.union);
+            }
+            schema.oneOf = [];
+            break;
+        default:
+            schema.type = attribute.wp.type ?? "string";
+            break;
+    }
+    applyCommonConstraints(schema, attribute.typia.constraints);
+    return schema;
+}
+/**
+ * Builds a full JSON Schema document from a Typia manifest document.
+ *
+ * @param doc Manifest-derived attribute document.
+ * @returns A draft 2020-12 JSON Schema document for the manifest root object.
+ */
+export function manifestToJsonSchema(doc) {
+    const attributes = doc.attributes ?? {};
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        additionalProperties: false,
+        properties: Object.fromEntries(Object.entries(attributes).map(([key, value]) => [
+            key,
+            manifestAttributeToJsonSchema(value),
+        ])),
+        required: Object.entries(attributes)
+            .filter(([, value]) => value.ts.required !== false)
+            .map(([key]) => key),
+        title: doc.sourceType ?? "TypiaDocument",
+        type: "object",
+    };
+}
+/**
+ * Projects one generated wp-typia JSON Schema document into a consumer-facing profile.
+ *
+ * @param schema Existing generated JSON Schema document.
+ * @param options Projection profile options.
+ * @returns A cloned schema document adjusted for the requested profile.
+ */
+export function projectJsonSchemaDocument(schema, options) {
+    if (options.profile === "rest") {
+        return cloneJsonSchemaNode(schema);
+    }
+    if (options.profile === "ai-structured-output") {
+        return projectSchemaObjectForAiStructuredOutput(schema, "#");
+    }
+    throw new Error(`Unsupported JSON Schema projection profile "${String(options.profile)}".`);
+}
+/**
+ * Wraps a manifest-derived JSON Schema document in a minimal OpenAPI 3.1 shell.
+ *
+ * @param doc Manifest-derived attribute document.
+ * @param info Optional OpenAPI document metadata.
+ * @returns An OpenAPI document containing the schema as a single component.
+ */
+export function manifestToOpenApi(doc, info = {}) {
+    const schemaName = doc.sourceType ?? "TypiaDocument";
+    return {
+        components: {
+            schemas: {
+                [schemaName]: manifestToJsonSchema(doc),
+            },
+        },
+        info: {
+            title: info.title ?? schemaName,
+            version: info.version ?? "1.0.0",
+            ...(info.description ? { description: info.description } : {}),
+        },
+        openapi: "3.1.0",
+        paths: {},
+    };
+}
+function createOpenApiSchemaRef(schemaName) {
+    return {
+        $ref: `#/components/schemas/${schemaName}`,
+    };
+}
+function formatEndpointDescription(endpoint) {
+    return `${endpoint.operationId} (${endpoint.method} ${endpoint.path})`;
+}
+function normalizeWordPressAuthDefinition(wordpressAuth) {
+    if (!wordpressAuth) {
+        return undefined;
+    }
+    if (wordpressAuth.mechanism !==
+        WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_PUBLIC_TOKEN_MECHANISM) {
+        return {
+            mechanism: wordpressAuth.mechanism,
+        };
+    }
+    return {
+        mechanism: wordpressAuth.mechanism,
+        publicTokenField: wordpressAuth.publicTokenField ??
+            WP_TYPIA_OPENAPI_LITERALS.PUBLIC_WRITE_TOKEN_FIELD,
+    };
+}
+function deriveLegacyAuthModeFromNormalizedAuth(auth, wordpressAuth) {
+    if (auth === "public") {
+        return "public-read";
+    }
+    if (auth === "authenticated" &&
+        wordpressAuth?.mechanism ===
+            WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_REST_NONCE_MECHANISM) {
+        return "authenticated-rest-nonce";
+    }
+    if (auth === "public-write-protected" &&
+        wordpressAuth?.mechanism ===
+            WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_PUBLIC_TOKEN_MECHANISM) {
+        return "public-signed-token";
+    }
+    return undefined;
+}
+function compareNormalizedEndpointAuth(left, right) {
+    return (left.auth === right.auth &&
+        left.authMode === right.authMode &&
+        left.wordpressAuth?.mechanism === right.wordpressAuth?.mechanism &&
+        left.wordpressAuth?.publicTokenField === right.wordpressAuth?.publicTokenField);
+}
+/**
+ * Normalizes endpoint auth metadata into backend-neutral intent plus optional
+ * WordPress adapter details.
+ *
+ * This public runtime helper accepts either the authored `auth` and optional
+ * `wordpressAuth` shape or the deprecated `authMode` field. It validates that
+ * the provided fields are compatible, resolves the legacy compatibility mode,
+ * and returns a normalized definition without mutating the input endpoint.
+ *
+ * @param endpoint - Endpoint auth fields to normalize, including `auth`,
+ * `authMode`, `wordpressAuth`, and optional identity fields used in error
+ * messages (`operationId`, `path`, and `method`).
+ * @returns The normalized auth definition for the endpoint.
+ * @throws When `auth` and deprecated `authMode` conflict.
+ * @throws When `wordpressAuth` is attached to the `public` auth intent.
+ * @throws When the selected `wordpressAuth` mechanism is incompatible with the
+ * chosen auth intent.
+ * @throws When neither `auth` nor deprecated `authMode` is defined.
+ */
+export function normalizeEndpointAuthDefinition(endpoint) {
+    const endpointDescription = typeof endpoint.operationId === "string" &&
+        typeof endpoint.path === "string" &&
+        typeof endpoint.method === "string"
+        ? formatEndpointDescription(endpoint)
+        : "the current endpoint";
+    const nextWordPressAuth = normalizeWordPressAuthDefinition(endpoint.wordpressAuth);
+    let normalized = null;
+    if (endpoint.auth) {
+        normalized = {
+            auth: endpoint.auth,
+            authMode: deriveLegacyAuthModeFromNormalizedAuth(endpoint.auth, nextWordPressAuth),
+            ...(nextWordPressAuth ? { wordpressAuth: nextWordPressAuth } : {}),
+        };
+        if (endpoint.auth === "public" && nextWordPressAuth) {
+            throw new Error(`Endpoint "${endpointDescription}" cannot attach wordpressAuth when auth intent is "public".`);
+        }
+        if (endpoint.auth === "authenticated" &&
+            nextWordPressAuth?.mechanism ===
+                WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_PUBLIC_TOKEN_MECHANISM) {
+            throw new Error(`Endpoint "${endpointDescription}" uses auth intent "authenticated" but wordpressAuth mechanism "${nextWordPressAuth.mechanism}" only supports "public-write-protected".`);
+        }
+        if (endpoint.auth === "public-write-protected" &&
+            nextWordPressAuth?.mechanism ===
+                WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_REST_NONCE_MECHANISM) {
+            throw new Error(`Endpoint "${endpointDescription}" uses auth intent "public-write-protected" but wordpressAuth mechanism "${nextWordPressAuth.mechanism}" only supports "authenticated".`);
+        }
+    }
+    let legacyNormalized = null;
+    if (endpoint.authMode) {
+        legacyNormalized =
+            endpoint.authMode === "public-read"
+                ? {
+                    auth: "public",
+                    authMode: "public-read",
+                }
+                : endpoint.authMode === "authenticated-rest-nonce"
+                    ? {
+                        auth: "authenticated",
+                        authMode: "authenticated-rest-nonce",
+                        wordpressAuth: {
+                            mechanism: WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_REST_NONCE_MECHANISM,
+                        },
+                    }
+                    : {
+                        auth: "public-write-protected",
+                        authMode: "public-signed-token",
+                        wordpressAuth: {
+                            mechanism: WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_PUBLIC_TOKEN_MECHANISM,
+                            publicTokenField: WP_TYPIA_OPENAPI_LITERALS.PUBLIC_WRITE_TOKEN_FIELD,
+                        },
+                    };
+    }
+    if (normalized && legacyNormalized) {
+        if (!compareNormalizedEndpointAuth(normalized, legacyNormalized)) {
+            throw new Error(`Endpoint "${endpointDescription}" defines conflicting auth metadata between auth/wordpressAuth and deprecated authMode.`);
+        }
+        return normalized;
+    }
+    if (normalized) {
+        return normalized;
+    }
+    if (legacyNormalized) {
+        return legacyNormalized;
+    }
+    throw new Error(`Endpoint "${endpointDescription}" must define either auth or deprecated authMode.`);
+}
+function getContractSchemaName(contractKey, contract, endpoint, role = "contract") {
+    if (!contract) {
+        if (endpoint) {
+            throw new Error(`Missing ${role} contract "${contractKey}" while building endpoint "${formatEndpointDescription(endpoint)}"`);
+        }
+        throw new Error(`Missing OpenAPI contract definition for "${contractKey}"`);
+    }
+    return contract.schemaName ?? contract.document.sourceType ?? contractKey;
+}
+function buildQueryParameters(contract) {
+    const attributes = contract.document.attributes ?? {};
+    return Object.entries(attributes).map(([name, attribute]) => ({
+        in: WP_TYPIA_OPENAPI_LITERALS.QUERY_LOCATION,
+        name,
+        required: attribute.ts.required !== false,
+        schema: manifestAttributeToJsonSchema(attribute),
+    }));
+}
+function createSuccessResponse(schemaName) {
+    return {
+        content: {
+            [WP_TYPIA_OPENAPI_LITERALS.JSON_CONTENT_TYPE]: {
+                schema: createOpenApiSchemaRef(schemaName),
+            },
+        },
+        description: WP_TYPIA_OPENAPI_LITERALS.SUCCESS_RESPONSE_DESCRIPTION,
+    };
+}
+function buildEndpointOpenApiOperation(endpoint, contracts) {
+    const normalizedAuth = normalizeEndpointAuthDefinition(endpoint);
+    const operation = {
+        operationId: endpoint.operationId,
+        responses: {
+            "200": createSuccessResponse(getContractSchemaName(endpoint.responseContract, contracts[endpoint.responseContract], endpoint, "response")),
+        },
+        tags: [...endpoint.tags],
+        [WP_TYPIA_OPENAPI_EXTENSION_KEYS.AUTH_INTENT]: normalizedAuth.auth,
+        ...(normalizedAuth.authMode
+            ? {
+                [WP_TYPIA_OPENAPI_EXTENSION_KEYS.AUTH_POLICY]: normalizedAuth.authMode,
+            }
+            : {}),
+    };
+    if (typeof endpoint.summary === "string" && endpoint.summary.length > 0) {
+        operation.summary = endpoint.summary;
+    }
+    if (typeof endpoint.queryContract === "string") {
+        operation.parameters = buildQueryParameters(contracts[endpoint.queryContract] ??
+            (() => {
+                throw new Error(`Missing query contract "${endpoint.queryContract}" while building endpoint "${formatEndpointDescription(endpoint)}"`);
+            })());
+    }
+    if (typeof endpoint.bodyContract === "string") {
+        operation.requestBody = {
+            content: {
+                [WP_TYPIA_OPENAPI_LITERALS.JSON_CONTENT_TYPE]: {
+                    schema: createOpenApiSchemaRef(getContractSchemaName(endpoint.bodyContract, contracts[endpoint.bodyContract], endpoint, "request body")),
+                },
+            },
+            required: true,
+        };
+    }
+    if (normalizedAuth.wordpressAuth?.mechanism ===
+        WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_REST_NONCE_MECHANISM) {
+        operation.security = [
+            {
+                [WP_TYPIA_OPENAPI_LITERALS.WP_REST_NONCE_SCHEME]: [],
+            },
+        ];
+    }
+    else if (normalizedAuth.wordpressAuth?.mechanism ===
+        WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_PUBLIC_TOKEN_MECHANISM) {
+        operation[WP_TYPIA_OPENAPI_EXTENSION_KEYS.PUBLIC_TOKEN_FIELD] =
+            normalizedAuth.wordpressAuth.publicTokenField ??
+                WP_TYPIA_OPENAPI_LITERALS.PUBLIC_WRITE_TOKEN_FIELD;
+    }
+    return operation;
+}
+/**
+ * Build a complete OpenAPI 3.1 document from contract manifests and route metadata.
+ *
+ * @param options Aggregate contract and endpoint definitions for the REST surface.
+ * @returns A JSON-compatible OpenAPI document with paths, components, and auth metadata.
+ */
+export function buildEndpointOpenApiDocument(options) {
+    const contractEntries = Object.entries(options.contracts);
+    const schemas = Object.fromEntries(contractEntries.map(([contractKey, contract]) => [
+        getContractSchemaName(contractKey, contract),
+        manifestToJsonSchema(contract.document),
+    ]));
+    const paths = {};
+    const topLevelTags = [...new Set(options.endpoints.flatMap((endpoint) => endpoint.tags))]
+        .filter((tag) => typeof tag === "string" && tag.length > 0)
+        .map((name) => ({ name }));
+    const usesWpRestNonce = options.endpoints.some((endpoint) => normalizeEndpointAuthDefinition(endpoint).wordpressAuth?.mechanism ===
+        WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_REST_NONCE_MECHANISM);
+    for (const endpoint of options.endpoints) {
+        const pathItem = paths[endpoint.path] ?? {};
+        pathItem[endpoint.method.toLowerCase()] = buildEndpointOpenApiOperation(endpoint, options.contracts);
+        paths[endpoint.path] = pathItem;
+    }
+    return {
+        components: {
+            schemas,
+            ...(usesWpRestNonce
+                ? {
+                    securitySchemes: {
+                        [WP_TYPIA_OPENAPI_LITERALS.WP_REST_NONCE_SCHEME]: {
+                            description: "WordPress REST nonce sent in the X-WP-Nonce header.",
+                            in: "header",
+                            name: WP_TYPIA_OPENAPI_LITERALS.WP_REST_NONCE_HEADER,
+                            type: "apiKey",
+                        },
+                    },
+                }
+                : {}),
+        },
+        info: {
+            title: options.info?.title ?? "Typia REST API",
+            version: options.info?.version ?? "1.0.0",
+            ...(options.info?.description ? { description: options.info.description } : {}),
+        },
+        openapi: "3.1.0",
+        paths,
+        ...(topLevelTags.length > 0 ? { tags: topLevelTags } : {}),
+    };
+}

package/dist/runtime/starter-manifests.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Scaffold-time starter manifest builders for generated projects.
+ *
+ * These helpers create placeholder `typia.manifest.json` artifacts so fresh
+ * scaffolds can resolve runtime imports before the first canonical sync run.
+ */
+import type { ManifestDocument } from "./migration-types.js";
+import type { ScaffoldTemplateVariables } from "./scaffold.js";
+/**
+ * Builds the starter manifest used by generated compound child blocks.
+ */
+export declare function buildCompoundChildStarterManifestDocument(childTypeName: string, childTitle: string, bodyPlaceholder?: string): ManifestDocument;
+/**
+ * Returns the starter manifest files that should be seeded for a built-in
+ * template before the first sync.
+ */
+export declare function getStarterManifestFiles(templateId: string, variables: ScaffoldTemplateVariables): Array<{
+    document: ManifestDocument;
+    relativePath: string;
+}>;
+/**
+ * Serializes a starter manifest using the generated-project JSON formatting
+ * convention.
+ */
+export declare function stringifyStarterManifest(document: ManifestDocument): string;