@wp-typia/project-tools 0.23.0 → 0.24.0

package/dist/runtime/json-utils.js

@@ -1,7 +1,81 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
 /**
- * Re-exports JSON cloning helpers from `@wp-typia/block-runtime`.
- * This adapter keeps the existing project-tools module path stable while the
- * runtime implementation now lives in block-runtime.
+ * JSON helpers shared by project-tools runtime modules.
+ *
+ * File-backed runtime JSON readers should use `safeJsonParse`,
+ * `readJsonFileSync`, or `readJsonFile` so malformed JSON reports the file path
+ * and operation context. Raw `JSON.parse` remains intentional for trusted
+ * in-memory clones, subprocess output, test fixtures, generated workspace
+ * script templates that embed their own path-aware parse handling,
+ * package-version manifest cache probes with colocated path-aware wrappers,
+ * and cache/discovery probes that immediately catch malformed documents to
+ * continue with fallback behavior.
+ *
+ * This module keeps `cloneJsonValue` local instead of re-exporting the
+ * block-runtime helper so Bunli CLI bundles that only need project-tools JSON
+ * readers do not need to resolve the block-runtime subpath at runtime.
+ *
  * @module
  */
-export * from "@wp-typia/block-runtime/json-utils";
+/**
+ * Create a deep clone of a JSON-serializable value.
+ *
+ * @remarks
+ * Values that are not JSON-serializable, such as functions, `undefined`,
+ * `BigInt`, class instances, and `Date` objects, are not preserved faithfully.
+ *
+ * @param value JSON-compatible data to clone.
+ * @returns A deep-cloned copy created with `JSON.parse(JSON.stringify(...))`.
+ */
+export function cloneJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function formatJsonParseTarget({ context, filePath }) {
+    const operation = context?.trim() || "JSON";
+    return filePath ? `${operation} at ${filePath}` : operation;
+}
+/**
+ * Parse JSON and include operation/file context when decoding fails.
+ *
+ * @param source Raw JSON source text.
+ * @param options Optional file path and human-readable operation context.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ * @throws {Error} When the source is malformed JSON.
+ */
+export function safeJsonParse(source, options = {}) {
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${formatJsonParseTarget(options)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Read and parse a JSON file synchronously with path-aware parse errors.
+ *
+ * @param filePath JSON file path to read.
+ * @param options Optional parse context. `filePath` is always set from the
+ * reader argument.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ */
+export function readJsonFileSync(filePath, options = {}) {
+    return safeJsonParse(fs.readFileSync(filePath, "utf8"), {
+        ...options,
+        filePath,
+    });
+}
+/**
+ * Read and parse a JSON file asynchronously with path-aware parse errors.
+ *
+ * @param filePath JSON file path to read.
+ * @param options Optional parse context. `filePath` is always set from the
+ * reader argument.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ */
+export async function readJsonFile(filePath, options = {}) {
+    return safeJsonParse(await fsp.readFile(filePath, "utf8"), {
+        ...options,
+        filePath,
+    });
+}

package/dist/runtime/local-dev-presets.js

@@ -8,6 +8,8 @@ import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { formatRunScript, } from "./package-managers.js";
+import { DEFAULT_WORDPRESS_ENV_VERSION } from "./package-versions.js";
+import { readJsonFile } from "./json-utils.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, SHARED_TEST_PRESET_TEMPLATE_ROOT, SHARED_WP_ENV_PRESET_TEMPLATE_ROOT, } from "./template-registry.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
 function templateHasPersistenceSync(templateId, compoundPersistenceEnabled) {
@@ -54,7 +56,9 @@ function getDevScript(packageManager, compoundPersistenceEnabled, templateId) {
 }
 async function mutatePackageJson(projectDir, mutate) {
     const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "local dev package manifest",
+    });
     mutate(packageJson);
     await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
 }
@@ -103,7 +107,7 @@ export async function applyGeneratedProjectDxPackageJson({ compoundPersistenceEn
                 : {}),
         };
         if (withWpEnv || withTestPreset) {
-            packageJson.devDependencies["@wordpress/env"] = "^11.2.0";
+            packageJson.devDependencies["@wordpress/env"] = DEFAULT_WORDPRESS_ENV_VERSION;
         }
         if (withTestPreset) {
             packageJson.devDependencies["@playwright/test"] = "^1.54.2";

package/dist/runtime/migration-ui-capability.js

@@ -2,6 +2,7 @@ import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { getPackageVersions } from "./package-versions.js";
 import { formatPackageExecCommand } from "./package-managers.js";
+import { readJsonFile } from "./json-utils.js";
 import { seedProjectMigrations } from "./migrations.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
 import { SHARED_MIGRATION_UI_TEMPLATE_ROOT, } from "./template-registry.js";
@@ -10,7 +11,9 @@ const BLOCK_METADATA_IMPORT_LINE = "import metadata from './block-metadata';";
 const LEGACY_BLOCK_JSON_IMPORT_LINE = "import metadata from './block.json';";
 async function mutatePackageJson(projectDir, mutate) {
     const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "migration UI package manifest",
+    });
     mutate(packageJson);
     await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
 }

package/dist/runtime/migration-utils.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { formatRunScript, inferPackageManagerId, parsePackageManagerField, } from './package-managers.js';
 import { isPlainObject } from './object-utils.js';
+import { readJsonFileSync } from './json-utils.js';
 export { cloneJsonValue } from './json-utils.js';
 const MIGRATION_VERSION_LABEL_PATTERN = /^v([1-9]\d*)$/;
 const LEGACY_SEMVER_MIGRATION_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
@@ -66,7 +67,9 @@ export function createTransformFixtureValue(attribute, pathLabel) {
     }
 }
 export function readJson(filePath) {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return readJsonFileSync(filePath, {
+        context: 'migration JSON file',
+    });
 }
 export function renderPhpValue(value, indentLevel) {
     const indent = '\t'.repeat(indentLevel);

package/dist/runtime/package-managers.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { readJsonFileSync } from "./json-utils.js";
 const PACKAGE_MANAGER_DATA = [
     {
         id: "bun",
@@ -73,12 +74,16 @@ function readPackageManagerField(projectDir) {
         if (!fs.existsSync(packageJsonPath)) {
             return undefined;
         }
-        const manifest = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        const manifest = readJsonFileSync(packageJsonPath, {
+            context: "package manager manifest",
+        });
         return typeof manifest.packageManager === "string"
             ? manifest.packageManager
             : undefined;
     }
     catch {
+        // Package manager inference intentionally falls back to lockfile signals
+        // when package.json is absent or malformed.
         return undefined;
     }
 }

package/dist/runtime/package-versions.d.ts

@@ -23,6 +23,7 @@ export declare const DEFAULT_WORDPRESS_CORE_ABILITIES_VERSION = "^0.9.0";
 export declare const DEFAULT_WORDPRESS_CORE_DATA_VERSION = "^7.44.0";
 export declare const DEFAULT_WORDPRESS_DATA_VERSION = "^9.28.0";
 export declare const DEFAULT_WORDPRESS_DATAVIEWS_VERSION = "^14.1.0";
+export declare const DEFAULT_WORDPRESS_ENV_VERSION = "^11.2.0";
 export declare const DEFAULT_WP_TYPIA_DATAVIEWS_VERSION = "^0.1.1";
 /**
  * Resolve a managed package version range from linked workspace packages first,

package/dist/runtime/package-versions.js

@@ -20,6 +20,7 @@ export const DEFAULT_WORDPRESS_CORE_ABILITIES_VERSION = '^0.9.0';
 export const DEFAULT_WORDPRESS_CORE_DATA_VERSION = '^7.44.0';
 export const DEFAULT_WORDPRESS_DATA_VERSION = '^9.28.0';
 export const DEFAULT_WORDPRESS_DATAVIEWS_VERSION = '^14.1.0';
+export const DEFAULT_WORDPRESS_ENV_VERSION = '^11.2.0';
 export const DEFAULT_WP_TYPIA_DATAVIEWS_VERSION = '^0.1.1';
 let cachedPackageVersions = null;
 function normalizeVersionRange(value) {
@@ -92,7 +93,12 @@ function readPackageManifest(location) {
     if (!location.packageJsonPath || location.source === null) {
         return null;
     }
-    return JSON.parse(location.source);
+    try {
+        return JSON.parse(location.source);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse package version manifest at ${location.packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 function tryReadPackageManifest(location) {
     if (!location) {
@@ -170,6 +176,7 @@ export function getPackageVersions() {
     const createManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, 'package.json'));
     const monorepoManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', '..', 'package.json'));
     const blockRuntimeManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', 'wp-typia-block-runtime', 'package.json'));
+    const blockTypesManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', 'wp-typia-block-types', 'package.json'));
     const wpTypiaManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', 'wp-typia', 'package.json'));
     const installedProjectToolsManifestLocation = resolveInstalledPackageManifestLocation('@wp-typia/project-tools');
     const installedApiClientManifestLocation = resolveInstalledPackageManifestLocation('@wp-typia/api-client');
@@ -185,6 +192,7 @@ export function getPackageVersions() {
         createManifestLocation,
         monorepoManifestLocation,
         blockRuntimeManifestLocation,
+        blockTypesManifestLocation,
         wpTypiaManifestLocation,
         installedProjectToolsManifestLocation,
         installedApiClientManifestLocation,
@@ -207,18 +215,23 @@ export function getPackageVersions() {
     const blockRuntimeManifest = readPackageManifest(blockRuntimeManifestLocation) ??
         readPackageManifest(installedBlockRuntimeManifestLocation) ??
         {};
+    const blockTypesManifest = readPackageManifest(blockTypesManifestLocation) ??
+        readPackageManifest(installedBlockTypesManifestLocation) ??
+        {};
     const wpTypiaManifest = readPackageManifest(wpTypiaManifestLocation) ??
         readPackageManifest(installedWpTypiaManifestLocation) ??
         {};
     const blockRuntimeDependencyVersion = normalizeVersionRange(createManifest.dependencies?.['@wp-typia/block-runtime']);
+    const blockTypesDependencyVersion = normalizeVersionRange(createManifest.dependencies?.['@wp-typia/block-types']);
     const versions = {
         apiClientPackageVersion: normalizeVersionRange(createManifest.dependencies?.['@wp-typia/api-client'] ??
             readPackageManifest(installedApiClientManifestLocation)?.version),
         blockRuntimePackageVersion: blockRuntimeDependencyVersion !== DEFAULT_VERSION_RANGE
             ? blockRuntimeDependencyVersion
             : normalizeVersionRange(blockRuntimeManifest.version),
-        blockTypesPackageVersion: normalizeVersionRange(createManifest.dependencies?.['@wp-typia/block-types'] ??
-            readPackageManifest(installedBlockTypesManifestLocation)?.version),
+        blockTypesPackageVersion: blockTypesDependencyVersion !== DEFAULT_VERSION_RANGE
+            ? blockTypesDependencyVersion
+            : normalizeVersionRange(blockTypesManifest.version),
         projectToolsPackageVersion: normalizeVersionRange(createManifest.version),
         restPackageVersion: normalizeVersionRange(createManifest.dependencies?.['@wp-typia/rest'] ??
             readPackageManifest(installedRestManifestLocation)?.version),

package/dist/runtime/pattern-catalog.d.ts

@@ -0,0 +1,122 @@
+import { type ParsedBlockPatternBlock } from "@wp-typia/block-runtime/metadata-core";
+export declare const PATTERN_CATALOG_SCOPE_IDS: readonly ["full", "section"];
+export type PatternCatalogScope = (typeof PATTERN_CATALOG_SCOPE_IDS)[number];
+export type PatternCatalogEntry = {
+    contentFile?: string;
+    file?: string;
+    scope?: string;
+    sectionRole?: string;
+    slug: string;
+    tags?: readonly string[];
+    thumbnailUrl?: string;
+    title?: string;
+};
+export type PatternCatalogDiagnosticSeverity = "error" | "warning";
+export type PatternCatalogDiagnosticCode = "duplicate-pattern-slug" | "invalid-pattern-content-file" | "invalid-pattern-scope" | "invalid-pattern-section-role" | "invalid-pattern-section-role-convention" | "invalid-pattern-section-role-marker" | "invalid-pattern-slug" | "invalid-pattern-tag" | "invalid-pattern-thumbnail-url" | "mismatched-pattern-section-role" | "missing-pattern-content-file" | "missing-pattern-section-role" | "missing-pattern-section-role-marker" | "duplicate-pattern-section-role-marker" | "unknown-pattern-section-role-marker";
+export type PatternCatalogDiagnostic = {
+    code: PatternCatalogDiagnosticCode;
+    message: string;
+    patternSlug?: string;
+    severity: PatternCatalogDiagnosticSeverity;
+};
+/**
+ * Convention used to discover section role markers in serialized pattern
+ * content. Defaults target `core/group` wrappers with a `section` base class,
+ * `section--{role}` role class tokens, and `metadata.sectionRole` attributes.
+ */
+export type PatternCatalogSectionRoleConvention = {
+    /**
+     * Serialized block name used as the section wrapper. Defaults to
+     * `core/group`.
+     */
+    wrapperBlockName?: string;
+    /**
+     * Optional class that marks a wrapper block as section-like even when the
+     * role marker is missing. Defaults to `section`.
+     */
+    baseClassName?: string;
+    /**
+     * Class token pattern where exactly one `{role}` placeholder is replaced by
+     * the section role slug. Defaults to `section--{role}`.
+     */
+    roleClassNamePattern?: string;
+    /**
+     * Dot-separated block attribute paths that can carry role slugs. Defaults to
+     * `metadata.sectionRole`.
+     */
+    roleAttributePaths?: readonly string[];
+    /**
+     * Warn when a full pattern repeats the same section role marker. Defaults to
+     * `false`.
+     */
+    requireUniqueFullPatternRoles?: boolean;
+};
+/**
+ * Section wrapper match extracted from a parsed WordPress block tree.
+ */
+export type PatternCatalogSectionRoleMatch = {
+    blockName: string;
+    blockPath: string;
+    roles: readonly string[];
+};
+/**
+ * Options for validating typed pattern catalog entries and, when `projectDir`
+ * is provided, their serialized pattern content. Set `sectionRoleConvention` to
+ * `false` to keep file existence checks but opt out of section-role marker
+ * validation.
+ */
+export type PatternCatalogValidationOptions = {
+    projectDir?: string;
+    sectionRoleConvention?: PatternCatalogSectionRoleConvention | false;
+};
+export type PatternCatalogValidationResult = {
+    diagnostics: PatternCatalogDiagnostic[];
+    errors: PatternCatalogDiagnostic[];
+    warnings: PatternCatalogDiagnostic[];
+};
+/**
+ * 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 declare function extractPatternSectionRolesFromAttributes(attributes: Record<string, unknown>, convention?: PatternCatalogSectionRoleConvention): string[];
+/**
+ * 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 declare function extractPatternSectionRoleMatches(blocks: readonly ParsedBlockPatternBlock[], convention?: PatternCatalogSectionRoleConvention): PatternCatalogSectionRoleMatch[];
+/**
+ * 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 declare function isValidPatternThumbnailUrl(value: string): boolean;
+export declare function resolvePatternCatalogContentFile(pattern: Pick<PatternCatalogEntry, "contentFile" | "file">): string | undefined;
+/**
+ * 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 declare function validatePatternCatalog(patterns: readonly PatternCatalogEntry[], options?: PatternCatalogValidationOptions): PatternCatalogValidationResult;
+/**
+ * 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 declare function formatPatternCatalogDiagnostics(diagnostics: readonly PatternCatalogDiagnostic[]): string;