@wp-typia/project-tools 0.23.0 → 0.24.0

package/dist/runtime/pattern-catalog.js

@@ -0,0 +1,471 @@
+import fs from "node:fs";
+import path from "node:path";
+import { validateBlockPatternContentNesting, } from "@wp-typia/block-runtime/metadata-core";
+export const PATTERN_CATALOG_SCOPE_IDS = ["full", "section"];
+const PATTERN_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/u;
+const PATTERN_SECTION_ROLE_PATTERN = PATTERN_SLUG_PATTERN;
+const PATTERN_TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
+const PATTERN_CONTENT_FILE_ROOT = "src/patterns/";
+const DEFAULT_SECTION_ROLE_CONVENTION = {
+    baseClassName: "section",
+    requireUniqueFullPatternRoles: false,
+    roleAttributePaths: ["metadata.sectionRole"],
+    roleClassNamePattern: "section--{role}",
+    wrapperBlockName: "core/group",
+};
+function createPatternCatalogDiagnostic(diagnostic) {
+    return diagnostic;
+}
+function isPatternCatalogScope(value) {
+    return PATTERN_CATALOG_SCOPE_IDS.includes(value);
+}
+function isSafeRelativePath(value) {
+    return (value.length > 0 &&
+        !path.isAbsolute(value) &&
+        !value.includes("\\") &&
+        !value.split(/[\\/]+/u).includes("..") &&
+        !/[<>:"|?*\u0000-\u001F]/u.test(value));
+}
+function isPatternContentFilePath(value) {
+    if (!isSafeRelativePath(value) ||
+        !value.startsWith(PATTERN_CONTENT_FILE_ROOT) ||
+        !value.endsWith(".php")) {
+        return false;
+    }
+    const patternRelativePath = value.slice(PATTERN_CONTENT_FILE_ROOT.length);
+    const segments = patternRelativePath.split("/");
+    return ((segments.length === 1 || segments.length === 2) &&
+        segments.every((segment) => segment.length > 0));
+}
+function normalizeSectionRoleConventionInput(convention = {}) {
+    return {
+        baseClassName: convention.baseClassName ??
+            DEFAULT_SECTION_ROLE_CONVENTION.baseClassName,
+        requireUniqueFullPatternRoles: convention.requireUniqueFullPatternRoles ??
+            DEFAULT_SECTION_ROLE_CONVENTION.requireUniqueFullPatternRoles,
+        roleAttributePaths: convention.roleAttributePaths ??
+            DEFAULT_SECTION_ROLE_CONVENTION.roleAttributePaths,
+        roleClassNamePattern: convention.roleClassNamePattern ??
+            DEFAULT_SECTION_ROLE_CONVENTION.roleClassNamePattern,
+        wrapperBlockName: convention.wrapperBlockName ??
+            DEFAULT_SECTION_ROLE_CONVENTION.wrapperBlockName,
+    };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function createRoleClassNamePattern(pattern) {
+    const parts = pattern.split("{role}");
+    if (parts.length !== 2) {
+        throw new Error(`roleClassNamePattern must contain exactly one "{role}" placeholder.`);
+    }
+    return new RegExp(`^${escapeRegExp(parts[0] ?? "")}(?<role>\\S*)${escapeRegExp(parts[1] ?? "")}$`, "u");
+}
+function normalizeSectionRoleConvention(convention = {}) {
+    const normalized = normalizeSectionRoleConventionInput(convention);
+    return {
+        ...normalized,
+        roleClassNamePatternRegExp: createRoleClassNamePattern(normalized.roleClassNamePattern),
+    };
+}
+function getClassNameTokens(attributes) {
+    const className = attributes.className;
+    if (typeof className !== "string") {
+        return [];
+    }
+    return className.split(/\s+/u).filter((token) => token.length > 0);
+}
+function getAttributePathValue(attributes, pathName) {
+    return pathName.split(".").reduce((current, segment) => {
+        if (current !== null &&
+            typeof current === "object" &&
+            !Array.isArray(current) &&
+            Object.prototype.hasOwnProperty.call(current, segment)) {
+            return current[segment];
+        }
+        return undefined;
+    }, attributes);
+}
+function collectStringValues(value) {
+    if (typeof value === "string") {
+        return [value];
+    }
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === "string");
+    }
+    return [];
+}
+function uniqueValues(values) {
+    return [...new Set(values)];
+}
+function formatRoleList(roles) {
+    if (roles.length === 0) {
+        return "none";
+    }
+    return roles.map((role) => `"${role}"`).join(", ");
+}
+function formatBlockPaths(paths) {
+    return paths.map((blockPath) => `at ${blockPath}`).join(", ");
+}
+function describeRoleMarkerConvention(convention) {
+    return `${convention.wrapperBlockName} wrappers with class "${convention.roleClassNamePattern}" or attributes ${convention.roleAttributePaths.join(", ")}`;
+}
+function isSectionWrapperCandidate(block, roles, convention) {
+    if (block.blockName !== convention.wrapperBlockName) {
+        return false;
+    }
+    if (roles.length > 0) {
+        return true;
+    }
+    return getClassNameTokens(block.attributes).includes(convention.baseClassName);
+}
+function collectSectionRoleMatches(blocks, convention, pathSegments = []) {
+    return blocks.flatMap((block, index) => {
+        const blockPathSegments = [
+            ...pathSegments,
+            `${block.blockName}[${index}]`,
+        ];
+        const blockPath = blockPathSegments.join(" > ");
+        const roles = extractPatternSectionRolesFromAttributes(block.attributes, convention);
+        const matches = isSectionWrapperCandidate(block, roles, convention)
+            ? [
+                {
+                    blockName: block.blockName,
+                    blockPath,
+                    roles,
+                },
+            ]
+            : [];
+        return [
+            ...matches,
+            ...collectSectionRoleMatches(block.innerBlocks, convention, blockPathSegments),
+        ];
+    });
+}
+function unescapeSerializedBlockCommentJsonQuotes(content) {
+    return content.replace(/<!--([\s\S]*?)-->/gu, (comment, body) => {
+        const source = body.trim();
+        if (!source.startsWith("wp:") && !source.startsWith("/wp:")) {
+            return comment;
+        }
+        return `<!--${body.replace(/\\"/gu, '"')}-->`;
+    });
+}
+/**
+ * Extract section role slugs from serialized block attributes using the
+ * configured class and metadata marker convention.
+ *
+ * @param attributes Parsed block attributes from serialized pattern content.
+ * @param convention Optional marker convention override.
+ * @returns Unique role marker values in discovery order.
+ */
+export function extractPatternSectionRolesFromAttributes(attributes, convention = {}) {
+    const normalized = normalizeSectionRoleConvention(convention);
+    const classRoles = getClassNameTokens(attributes)
+        .map((token) => normalized.roleClassNamePatternRegExp.exec(token)?.groups?.role)
+        .filter((role) => typeof role === "string");
+    const attributeRoles = normalized.roleAttributePaths.flatMap((pathName) => collectStringValues(getAttributePathValue(attributes, pathName)));
+    return uniqueValues([...classRoles, ...attributeRoles]);
+}
+/**
+ * Find section wrapper blocks and their role markers in parsed pattern content.
+ *
+ * @param blocks Parsed block tree returned by `validateBlockPatternContentNesting`.
+ * @param convention Optional marker convention override.
+ * @returns Section wrapper matches with serialized block paths.
+ */
+export function extractPatternSectionRoleMatches(blocks, convention = {}) {
+    return collectSectionRoleMatches(blocks, normalizeSectionRoleConvention(convention));
+}
+/**
+ * Validate pattern thumbnail references with the same URL/path rules used by
+ * catalog diagnostics and `wp-typia add pattern`.
+ *
+ * @param value Candidate thumbnail URL or relative project path.
+ * @returns Whether the value is an http(s) URL or safe relative project path.
+ */
+export function isValidPatternThumbnailUrl(value) {
+    if (value.length === 0) {
+        return false;
+    }
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return isSafeRelativePath(value);
+    }
+}
+export function resolvePatternCatalogContentFile(pattern) {
+    return pattern.contentFile ?? pattern.file;
+}
+function createKnownSectionRoleSet(patterns) {
+    return new Set(patterns
+        .map((pattern) => pattern.sectionRole)
+        .filter((sectionRole) => typeof sectionRole === "string" &&
+        PATTERN_SECTION_ROLE_PATTERN.test(sectionRole)));
+}
+function validatePatternContentSectionRoles({ content, contentFile, convention, knownSectionRoles, label, pattern, }) {
+    const diagnostics = [];
+    const parsed = validateBlockPatternContentNesting(content, {
+        allowExternalBlockNames: true,
+        nesting: {},
+        patternFile: contentFile,
+    });
+    let matches = collectSectionRoleMatches(parsed.blocks, convention);
+    const unescapedContent = unescapeSerializedBlockCommentJsonQuotes(content);
+    if (unescapedContent !== content) {
+        const unescapedParsed = validateBlockPatternContentNesting(unescapedContent, {
+            allowExternalBlockNames: true,
+            nesting: {},
+            patternFile: contentFile,
+        });
+        const unescapedMatches = collectSectionRoleMatches(unescapedParsed.blocks, convention);
+        if (unescapedMatches.some((match) => match.roles.length > 0) ||
+            matches.length === 0) {
+            matches = unescapedMatches;
+        }
+    }
+    const locatedRoles = matches.flatMap((match) => match.roles.map((role) => ({
+        blockPath: match.blockPath,
+        role,
+    })));
+    const invalidRoles = locatedRoles.filter(({ role }) => !PATTERN_SECTION_ROLE_PATTERN.test(role));
+    for (const invalidRole of uniqueValues(invalidRoles.map(({ role }) => role))) {
+        const paths = invalidRoles
+            .filter(({ role }) => role === invalidRole)
+            .map(({ blockPath }) => blockPath);
+        diagnostics.push(createPatternCatalogDiagnostic({
+            code: "invalid-pattern-section-role-marker",
+            message: `${label}: section role marker "${invalidRole}" in ${contentFile} must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens (${formatBlockPaths(paths)}).`,
+            patternSlug: pattern.slug,
+            severity: "error",
+        }));
+    }
+    const validLocatedRoles = locatedRoles.filter(({ role }) => PATTERN_SECTION_ROLE_PATTERN.test(role));
+    const validRoles = validLocatedRoles.map(({ role }) => role);
+    const uniqueValidRoles = uniqueValues(validRoles);
+    const unknownRoles = uniqueValidRoles.filter((role) => !knownSectionRoles.has(role));
+    for (const unknownRole of unknownRoles) {
+        const paths = validLocatedRoles
+            .filter(({ role }) => role === unknownRole)
+            .map(({ blockPath }) => blockPath);
+        diagnostics.push(createPatternCatalogDiagnostic({
+            code: "unknown-pattern-section-role-marker",
+            message: `${label}: section role marker "${unknownRole}" in ${contentFile} is not declared by any PATTERNS sectionRole (${formatBlockPaths(paths)}).`,
+            patternSlug: pattern.slug,
+            severity: "warning",
+        }));
+    }
+    const scope = pattern.scope ?? "full";
+    const expectedSectionRole = typeof pattern.sectionRole === "string" &&
+        PATTERN_SECTION_ROLE_PATTERN.test(pattern.sectionRole)
+        ? pattern.sectionRole
+        : undefined;
+    if (scope === "section" && expectedSectionRole) {
+        if (validRoles.length === 0) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "missing-pattern-section-role-marker",
+                message: `${label}: section-scoped pattern content in ${contentFile} must include section role marker "${expectedSectionRole}" using ${describeRoleMarkerConvention(convention)}.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        else if (!validRoles.includes(expectedSectionRole)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "mismatched-pattern-section-role",
+                message: `${label}: manifest sectionRole "${expectedSectionRole}" was not found in ${contentFile}; found ${formatRoleList(uniqueValidRoles)}.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+    }
+    if (scope === "full" && convention.requireUniqueFullPatternRoles) {
+        for (const role of uniqueValidRoles) {
+            const paths = validLocatedRoles
+                .filter((locatedRole) => locatedRole.role === role)
+                .map(({ blockPath }) => blockPath);
+            if (paths.length <= 1) {
+                continue;
+            }
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "duplicate-pattern-section-role-marker",
+                message: `${label}: full pattern content in ${contentFile} repeats section role marker "${role}" (${formatBlockPaths(paths)}).`,
+                patternSlug: pattern.slug,
+                severity: "warning",
+            }));
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Validate typed pattern catalog metadata declared in `scripts/block-config.ts`.
+ *
+ * The validator checks catalog shape, duplicate slugs, optional section-role
+ * rules, safe content file paths, and missing files when a workspace root is
+ * provided. With a workspace root, it also parses serialized block markup and
+ * compares section role markers against the catalog manifest.
+ *
+ * @param patterns Pattern catalog entries to validate.
+ * @param options Optional project root and section role marker convention.
+ * @returns Structured diagnostics split into errors and warnings.
+ */
+export function validatePatternCatalog(patterns, options = {}) {
+    const diagnostics = [];
+    const seenSlugs = new Map();
+    let sectionRoleConvention = null;
+    if (options.sectionRoleConvention !== false) {
+        try {
+            sectionRoleConvention = normalizeSectionRoleConvention(options.sectionRoleConvention);
+        }
+        catch (error) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-section-role-convention",
+                message: `sectionRoleConvention.roleClassNamePattern is invalid: ${error instanceof Error ? error.message : String(error)}`,
+                severity: "error",
+            }));
+        }
+    }
+    const knownSectionRoles = createKnownSectionRoleSet(patterns);
+    for (const [index, pattern] of patterns.entries()) {
+        const label = pattern.slug || `PATTERNS[${index}]`;
+        if (!PATTERN_SLUG_PATTERN.test(pattern.slug)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-slug",
+                message: `${label}: slug must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        const previousIndex = seenSlugs.get(pattern.slug);
+        if (previousIndex !== undefined) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "duplicate-pattern-slug",
+                message: `${label}: duplicate slug already declared at PATTERNS[${previousIndex}].`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        else {
+            seenSlugs.set(pattern.slug, index);
+        }
+        const scope = pattern.scope ?? "full";
+        if (!isPatternCatalogScope(scope)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-scope",
+                message: `${label}: scope must be one of ${PATTERN_CATALOG_SCOPE_IDS.join(", ")}.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        if (scope === "section" && !pattern.sectionRole) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "missing-pattern-section-role",
+                message: `${label}: section-scoped patterns must declare sectionRole.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        if (pattern.sectionRole !== undefined &&
+            !PATTERN_SECTION_ROLE_PATTERN.test(pattern.sectionRole)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-section-role",
+                message: `${label}: sectionRole must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        for (const [tagIndex, tag] of (pattern.tags ?? []).entries()) {
+            if (!PATTERN_TAG_PATTERN.test(tag)) {
+                diagnostics.push(createPatternCatalogDiagnostic({
+                    code: "invalid-pattern-tag",
+                    message: `${label}: tags[${tagIndex}] must contain only lowercase letters, numbers, and hyphens.`,
+                    patternSlug: pattern.slug,
+                    severity: "error",
+                }));
+            }
+        }
+        if (pattern.thumbnailUrl !== undefined &&
+            !isValidPatternThumbnailUrl(pattern.thumbnailUrl)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-thumbnail-url",
+                message: `${label}: thumbnailUrl must be an http(s) URL or safe relative project path.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        const contentFile = resolvePatternCatalogContentFile(pattern);
+        if (!contentFile) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "missing-pattern-content-file",
+                message: `${label}: contentFile or legacy file must point at the pattern PHP file.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+            continue;
+        }
+        if (!isPatternContentFilePath(contentFile)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-content-file",
+                message: `${label}: contentFile must be a safe relative project path directly under src/patterns/ or one nested directory under src/patterns/ and end in .php.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+            continue;
+        }
+        if (!options.projectDir) {
+            continue;
+        }
+        const absoluteContentFile = path.join(options.projectDir, contentFile);
+        if (!fs.existsSync(absoluteContentFile)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "missing-pattern-content-file",
+                message: `${label}: missing pattern content file ${contentFile}.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+            continue;
+        }
+        if (sectionRoleConvention) {
+            let content;
+            try {
+                content = fs.readFileSync(absoluteContentFile, "utf8");
+            }
+            catch (error) {
+                diagnostics.push(createPatternCatalogDiagnostic({
+                    code: "invalid-pattern-content-file",
+                    message: `${label}: failed to read pattern content file ${contentFile}: ${error instanceof Error ? error.message : String(error)}.`,
+                    patternSlug: pattern.slug,
+                    severity: "error",
+                }));
+                continue;
+            }
+            diagnostics.push(...validatePatternContentSectionRoles({
+                content,
+                contentFile,
+                convention: sectionRoleConvention,
+                knownSectionRoles,
+                label,
+                pattern,
+            }));
+        }
+    }
+    const warnings = diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+    const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    return {
+        diagnostics,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Render pattern catalog diagnostics for CLI, sync, and doctor output.
+ *
+ * @param diagnostics Diagnostics returned from {@link validatePatternCatalog}.
+ * @returns Human-readable lines with stable diagnostic codes.
+ */
+export function formatPatternCatalogDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => `- [${diagnostic.code}] ${diagnostic.message}`)
+        .join("\n");
+}

package/dist/runtime/post-meta-binding-fields.d.ts

@@ -0,0 +1,46 @@
+import type { WorkspacePostMetaInventoryEntry } from "./workspace-inventory-types.js";
+/**
+ * Field metadata extracted from a typed post-meta schema for a generated block
+ * bindings source.
+ *
+ * @property fallbackValue Editor preview value used when live post meta is unavailable.
+ * @property label Human-readable label derived from the schema property name.
+ * @property name Top-level schema property name used as the binding `field` arg.
+ * @property required Whether the field is listed in the schema's required array.
+ * @property schemaType Resolved JSON Schema type used to choose a preview value.
+ */
+export interface PostMetaBindingField {
+    fallbackValue: string;
+    label: string;
+    name: string;
+    required: boolean;
+    schemaType: string;
+}
+/**
+ * Load and extract binding fields from a post-meta JSON Schema artifact.
+ *
+ * @param projectDir Workspace root directory.
+ * @param postMeta Post-meta inventory entry that points to the schema file.
+ * @returns Promise resolving to the extracted top-level binding fields.
+ * @throws If the schema cannot be read or does not expose object properties.
+ */
+export declare function loadPostMetaBindingFields(projectDir: string, postMeta: WorkspacePostMetaInventoryEntry): Promise<PostMetaBindingField[]>;
+/**
+ * Synchronously load and extract binding fields from a post-meta JSON Schema artifact.
+ *
+ * @param projectDir Workspace root directory.
+ * @param postMeta Post-meta inventory entry that points to the schema file.
+ * @returns Extracted top-level binding fields.
+ * @throws If the schema cannot be read or does not expose object properties.
+ */
+export declare function loadPostMetaBindingFieldsSync(projectDir: string, postMeta: WorkspacePostMetaInventoryEntry): PostMetaBindingField[];
+/**
+ * Validate and resolve a top-level post-meta binding path.
+ *
+ * @param fields Binding fields extracted from the post-meta schema.
+ * @param postMetaSlug Post-meta contract slug used in diagnostics.
+ * @param metaPath User-provided field path to validate.
+ * @returns The matching binding field.
+ * @throws If the path is empty, nested, or missing from the schema fields.
+ */
+export declare function assertPostMetaBindingPath(fields: readonly PostMetaBindingField[], postMetaSlug: string, metaPath: string): PostMetaBindingField;

package/dist/runtime/post-meta-binding-fields.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import { readJsonFile, readJsonFileSync } from "./json-utils.js";
+const SUPPORTED_SCHEMA_TYPES = new Set([
+    "array",
+    "boolean",
+    "integer",
+    "number",
+    "object",
+    "string",
+]);
+function isJsonRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveSchemaType(schema) {
+    const type = schema.type;
+    if (typeof type === "string" && SUPPORTED_SCHEMA_TYPES.has(type)) {
+        return type;
+    }
+    if (Array.isArray(type) &&
+        type.every((entry) => typeof entry === "string")) {
+        const nonNullType = type.find((entry) => entry !== "null" && SUPPORTED_SCHEMA_TYPES.has(entry));
+        if (nonNullType) {
+            return nonNullType;
+        }
+    }
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        return "string";
+    }
+    return "unknown";
+}
+function resolveFallbackValue(name, schema, schemaType) {
+    const enumValue = Array.isArray(schema.enum)
+        ? schema.enum.find((entry) => typeof entry === "string")
+        : undefined;
+    if (typeof enumValue === "string") {
+        return enumValue;
+    }
+    switch (schemaType) {
+        case "array":
+            return "[]";
+        case "boolean":
+            return "false";
+        case "integer":
+        case "number":
+            return "0";
+        case "object":
+            return "{}";
+        default:
+            return `${name} preview`;
+    }
+}
+function resolveFieldLabel(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+function extractPostMetaBindingFields(schema, context) {
+    if (!isJsonRecord(schema) || !isJsonRecord(schema.properties)) {
+        throw new Error(`${context} must expose an object schema with top-level properties before it can back a binding source.`);
+    }
+    const required = Array.isArray(schema.required)
+        ? new Set(schema.required.filter((entry) => typeof entry === "string"))
+        : new Set();
+    const fields = Object.entries(schema.properties).map(([name, propertySchema]) => {
+        const property = isJsonRecord(propertySchema) ? propertySchema : {};
+        const schemaType = resolveSchemaType(property);
+        return {
+            fallbackValue: resolveFallbackValue(name, property, schemaType),
+            label: resolveFieldLabel(name),
+            name,
+            required: required.has(name),
+            schemaType,
+        };
+    });
+    if (fields.length === 0) {
+        throw new Error(`${context} does not expose any top-level properties that can back binding fields.`);
+    }
+    return fields;
+}
+/**
+ * Load and extract binding fields from a post-meta JSON Schema artifact.
+ *
+ * @param projectDir Workspace root directory.
+ * @param postMeta Post-meta inventory entry that points to the schema file.
+ * @returns Promise resolving to the extracted top-level binding fields.
+ * @throws If the schema cannot be read or does not expose object properties.
+ */
+export async function loadPostMetaBindingFields(projectDir, postMeta) {
+    const schemaPath = path.join(projectDir, postMeta.schemaFile);
+    const schema = await readJsonFile(schemaPath, {
+        context: `post meta schema for ${postMeta.slug}`,
+    });
+    return extractPostMetaBindingFields(schema, postMeta.schemaFile);
+}
+/**
+ * Synchronously load and extract binding fields from a post-meta JSON Schema artifact.
+ *
+ * @param projectDir Workspace root directory.
+ * @param postMeta Post-meta inventory entry that points to the schema file.
+ * @returns Extracted top-level binding fields.
+ * @throws If the schema cannot be read or does not expose object properties.
+ */
+export function loadPostMetaBindingFieldsSync(projectDir, postMeta) {
+    const schemaPath = path.join(projectDir, postMeta.schemaFile);
+    const schema = readJsonFileSync(schemaPath, {
+        context: `post meta schema for ${postMeta.slug}`,
+    });
+    return extractPostMetaBindingFields(schema, postMeta.schemaFile);
+}
+/**
+ * Validate and resolve a top-level post-meta binding path.
+ *
+ * @param fields Binding fields extracted from the post-meta schema.
+ * @param postMetaSlug Post-meta contract slug used in diagnostics.
+ * @param metaPath User-provided field path to validate.
+ * @returns The matching binding field.
+ * @throws If the path is empty, nested, or missing from the schema fields.
+ */
+export function assertPostMetaBindingPath(fields, postMetaSlug, metaPath) {
+    const trimmed = metaPath.trim();
+    if (!trimmed) {
+        throw new Error("Post meta binding path must include a value.");
+    }
+    if (trimmed.includes(".")) {
+        throw new Error(`Nested post meta path "${trimmed}" for "${postMetaSlug}" is not supported yet. Use one of the top-level fields: ${fields.map((field) => field.name).join(", ")}.`);
+    }
+    const field = fields.find((candidate) => candidate.name === trimmed);
+    if (!field) {
+        throw new Error(`Post meta path "${trimmed}" does not exist in the "${postMetaSlug}" schema. Expected one of: ${fields.map((candidate) => candidate.name).join(", ")}.`);
+    }
+    return field;
+}

package/dist/runtime/scaffold-bootstrap.js

@@ -9,6 +9,7 @@ import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-man
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, } from "./template-registry.js";
 import { getScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
 import { pathExists } from "./fs-async.js";
+import { readJsonFile, readJsonFileSync } from "./json-utils.js";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 /**
  * Ensures the scaffold target directory exists and is empty unless explicitly allowed.
@@ -32,7 +33,9 @@ function readGeneratedPackageJson(projectDir) {
     if (!fs.existsSync(packageJsonPath)) {
         return null;
     }
-    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return readJsonFileSync(packageJsonPath, {
+        context: "generated package manifest",
+    });
 }
 /**
  * Format the actionable error message used when a scaffold target directory
@@ -125,7 +128,9 @@ export function isOfficialWorkspaceProject(projectDir) {
  */
 export async function applyWorkspaceMigrationCapability(projectDir, packageManager) {
     const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "workspace package manifest",
+    });
     const wpTypiaPackageVersion = getPackageVersions().wpTypiaPackageVersion;
     const canonicalCliSpecifier = wpTypiaPackageVersion === "^0.0.0"
         ? "wp-typia"