@wp-typia/project-tools 0.24.0 → 0.24.2

package/dist/runtime/cli-add-help.js

@@ -14,7 +14,7 @@ export function formatAddHelpText() {
 	wp-typia add variation <name> --block <block-slug> [--dry-run]
 	wp-typia add style <name> --block <block-slug> [--dry-run]
 	wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug> [--dry-run]
-  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--tags <tag,...>] [--thumbnail-url <url>] [--dry-run]
+  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>] [--tag <tag>...] [--thumbnail-url <url>] [--dry-run]
   wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--from-post-meta|--post-meta <post-meta> [--meta-path <field>]] [--dry-run]
   wp-typia add contract <name> [--type <ExportedTypeName>] [--dry-run]
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <${REST_RESOURCE_METHOD_IDS.join(",")}>] [--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--dry-run]
@@ -30,6 +30,7 @@ Notes:
   Pass \`--dry-run\` to preview the workspace files that would change without writing them.
   Interactive add flows let you choose a template when \`--template\` is omitted; non-interactive runs default to \`basic\`.
   \`add core-variation\` registers editor-side variations for existing core or external blocks without generating block.json or Typia manifests.
+  Unknown \`core/*\` core-variation targets warn instead of failing so newer WordPress core blocks remain scaffoldable; third-party namespaces are allowed without local discovery.
   \`add admin-view\` scaffolds an opt-in DataViews-powered WordPress admin screen under \`src/admin-views/\`.
   Pass \`--source rest-resource:<slug>\` to reuse a list-capable REST resource.
   Pass \`--source core-data:postType/post\` or \`--source core-data:taxonomy/category\` to bind a WordPress-owned entity collection.
@@ -41,7 +42,7 @@ Notes:
   \`add variation\` targets an existing block slug from \`scripts/block-config.ts\`.
   \`add style\` registers a Block Styles option for an existing generated block.
   \`add transform\` adds a block-to-block transform into an existing generated block.
-  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\` and records typed catalog metadata in \`PATTERNS\`.
+  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\` and records typed catalog metadata in \`PATTERNS\`; pass \`--catalog-title "Hero Photo"\` to override the generated catalog title, pass \`--tags hero,landing\` for a comma-separated tag list, and repeat \`--tag hero --tag landing\` for single tag values.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`; pass \`--block\` and \`--attribute\` together to declare an end-to-end bindable attribute on an existing generated block. Pass \`--from-post-meta\` or \`--post-meta\` to generate a source backed by a typed post-meta contract; \`--meta-path\` selects one top-level field as the default binding arg.
   \`add contract\` registers a standalone TypeScript wire contract under \`src/contracts/\` and generates a stable JSON Schema artifact without creating PHP route glue.
   \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`. Use \`--route-pattern\`, \`--permission-callback\`, \`--controller-class\`, and \`--controller-extends\` when an existing WordPress controller or permission model needs to own part of the generated route surface.

package/dist/runtime/cli-add-types.d.ts

@@ -1,7 +1,7 @@
-import { PATTERN_CATALOG_SCOPE_IDS, type PatternCatalogScope } from "./pattern-catalog.js";
+import { PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, type PatternCatalogScope } from "./pattern-catalog.js";
 export { ADD_KIND_IDS } from "./cli-add-kind-ids.js";
 export type { AddKindId } from "./cli-add-kind-ids.js";
-export { PATTERN_CATALOG_SCOPE_IDS };
+export { PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, };
 export type { PatternCatalogScope };
 /**
  * Supported plugin-level REST resource methods accepted by

package/dist/runtime/cli-add-types.js

@@ -1,7 +1,7 @@
 import { suggestCloseId } from "./id-suggestions.js";
-import { PATTERN_CATALOG_SCOPE_IDS, } from "./pattern-catalog.js";
+import { PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, } from "./pattern-catalog.js";
 export { ADD_KIND_IDS } from "./cli-add-kind-ids.js";
-export { PATTERN_CATALOG_SCOPE_IDS };
+export { PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, };
 /**
  * Supported plugin-level REST resource methods accepted by
  * `wp-typia add rest-resource --methods`.

package/dist/runtime/cli-add-workspace-ai-source-emitters.js

@@ -1,14 +1,9 @@
 import { quoteTsString } from "./cli-add-shared.js";
 import { buildAiFeatureEndpointManifest } from "./ai-feature-artifacts.js";
 import { OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY, createScaffoldCompatibilityConfig, renderScaffoldCompatibilityConfig, resolveScaffoldCompatibilityPolicy, } from "./scaffold-compatibility.js";
+import { formatResolveRestNonceSource, indentMultiline, } from "./cli-add-workspace-rest-source-utils.js";
 import { toPascalCase, toTitleCase } from "./string-case.js";
 export { buildAiFeatureSyncScriptSource, } from "./cli-add-workspace-ai-sync-script-source.js";
-function indentMultiline(source, prefix) {
-    return source
-        .split("\n")
-        .map((line) => `${prefix}${line}`)
-        .join("\n");
-}
 /**
  * Build the workspace inventory entry written into `scripts/block-config.ts` for one AI feature.
  */
@@ -175,26 +170,7 @@ import {
 \trun${pascalCase}AiFeatureEndpoint,
 } from './api-client';
 
-function resolveRestNonce( fallback?: string ): string | undefined {
-\tif ( typeof fallback === 'string' && fallback.length > 0 ) {
-\t\treturn fallback;
-\t}
-
-\tif ( typeof window === 'undefined' ) {
-\t\treturn undefined;
-\t}
-
-\tconst wpApiSettings = (
-\t\twindow as typeof window & {
-\t\t\twpApiSettings?: { nonce?: string };
-\t\t}
-\t).wpApiSettings;
-
-\treturn typeof wpApiSettings?.nonce === 'string' &&
-\t\twpApiSettings.nonce.length > 0
-\t\t? wpApiSettings.nonce
-\t\t: undefined;
-}
+${formatResolveRestNonceSource("spaced")}
 
 function isPlainObject( value: unknown ): value is Record< string, unknown > {
 \treturn (

package/dist/runtime/cli-add-workspace-core-variation.d.ts

@@ -7,7 +7,8 @@ import { type RunAddCoreVariationCommandOptions } from "./cli-add-shared.js";
  * Defaults to `process.cwd()`.
  * @param options.targetBlockName Full `namespace/block` name that receives the variation.
  * @param options.variationName Human-entered variation name normalized into the generated slug.
- * @returns The normalized variation metadata and owning workspace directory.
+ * @returns The normalized variation metadata, owning workspace directory, and
+ * optional warnings for suspicious but forward-compatible targets.
  * @throws {Error} When the command is run outside an official workspace, the
  * target block name is not full `namespace/block` form, or the generated file
  * already exists.
@@ -17,4 +18,5 @@ export declare function runAddCoreVariationCommand({ cwd, targetBlockName, varia
     targetBlockName: string;
     variationFile: string;
     variationSlug: string;
+    warnings?: string[];
 }>;

package/dist/runtime/cli-add-workspace-core-variation.js

@@ -8,6 +8,101 @@ import { toKebabCase, toPascalCase, toTitleCase } from "./string-case.js";
 import { resolveWorkspaceProject } from "./workspace-project.js";
 const CORE_VARIATIONS_EDITOR_PLUGIN_SLUG = "core-variations";
 const CORE_VARIATION_USAGE = "wp-typia add core-variation <block-name> <name> or wp-typia add core-variation <name> --block <namespace/block>";
+const KNOWN_CORE_VARIATION_TARGETS = new Set([
+    "core/archives",
+    "core/audio",
+    "core/avatar",
+    "core/block",
+    "core/button",
+    "core/buttons",
+    "core/calendar",
+    "core/categories",
+    "core/code",
+    "core/column",
+    "core/columns",
+    "core/comment-author-name",
+    "core/comment-content",
+    "core/comment-date",
+    "core/comment-edit-link",
+    "core/comment-reply-link",
+    "core/comment-template",
+    "core/comments",
+    "core/comments-pagination",
+    "core/comments-pagination-next",
+    "core/comments-pagination-numbers",
+    "core/comments-pagination-previous",
+    "core/comments-title",
+    "core/cover",
+    "core/details",
+    "core/embed",
+    "core/file",
+    "core/footnotes",
+    "core/freeform",
+    "core/gallery",
+    "core/group",
+    "core/heading",
+    "core/home-link",
+    "core/html",
+    "core/image",
+    "core/latest-comments",
+    "core/latest-posts",
+    "core/legacy-widget",
+    "core/list",
+    "core/list-item",
+    "core/loginout",
+    "core/media-text",
+    "core/missing",
+    "core/more",
+    "core/navigation",
+    "core/navigation-link",
+    "core/navigation-submenu",
+    "core/nextpage",
+    "core/page-list",
+    "core/paragraph",
+    "core/pattern",
+    "core/post-author",
+    "core/post-author-biography",
+    "core/post-author-name",
+    "core/post-comments",
+    "core/post-comments-form",
+    "core/post-content",
+    "core/post-date",
+    "core/post-excerpt",
+    "core/post-featured-image",
+    "core/post-navigation-link",
+    "core/post-terms",
+    "core/post-template",
+    "core/post-title",
+    "core/preformatted",
+    "core/pullquote",
+    "core/query",
+    "core/query-no-results",
+    "core/query-pagination",
+    "core/query-pagination-next",
+    "core/query-pagination-numbers",
+    "core/query-pagination-previous",
+    "core/query-title",
+    "core/quote",
+    "core/read-more",
+    "core/rss",
+    "core/search",
+    "core/separator",
+    "core/shortcode",
+    "core/site-logo",
+    "core/site-tagline",
+    "core/site-title",
+    "core/social-link",
+    "core/social-links",
+    "core/spacer",
+    "core/table",
+    "core/table-of-contents",
+    "core/tag-cloud",
+    "core/template-part",
+    "core/term-description",
+    "core/text-columns",
+    "core/verse",
+    "core/video",
+]);
 const CORE_VARIATION_SIMPLE_CONTAINER_BLOCKS = new Set([
     "core/column",
     "core/cover",
@@ -54,6 +149,13 @@ function buildCoreVariationImportPath(ref) {
 function formatCoreVariationTitle(variationSlug) {
     return toTitleCase(variationSlug);
 }
+function getUnknownCoreVariationTargetWarning(targetBlockName) {
+    if (!targetBlockName.startsWith("core/") ||
+        KNOWN_CORE_VARIATION_TARGETS.has(targetBlockName)) {
+        return undefined;
+    }
+    return `Target block "${targetBlockName}" uses the WordPress core namespace but is not in wp-typia's known core block list. The variation was generated for forward compatibility; verify the block name or update wp-typia if this is a newer core block.`;
+}
 function assertCoreVariationDoesNotExist(projectDir, targetBlockName, variationSlug) {
     const variationFilePath = getCoreVariationFilePath(projectDir, targetBlockName, variationSlug);
     if (fs.existsSync(variationFilePath)) {
@@ -261,7 +363,8 @@ async function writeCoreVariationRegistry(projectDir, targetBlockName, textDomai
  * Defaults to `process.cwd()`.
  * @param options.targetBlockName Full `namespace/block` name that receives the variation.
  * @param options.variationName Human-entered variation name normalized into the generated slug.
- * @returns The normalized variation metadata and owning workspace directory.
+ * @returns The normalized variation metadata, owning workspace directory, and
+ * optional warnings for suspicious but forward-compatible targets.
  * @throws {Error} When the command is run outside an official workspace, the
  * target block name is not full `namespace/block` form, or the generated file
  * already exists.
@@ -270,6 +373,7 @@ export async function runAddCoreVariationCommand({ cwd = process.cwd(), targetBl
     const workspace = resolveWorkspaceProject(cwd);
     const resolvedTargetBlockName = assertFullBlockName(targetBlockName, "core-variation target");
     const variationSlug = assertValidGeneratedSlug("Core variation name", normalizeBlockSlug(variationName), CORE_VARIATION_USAGE);
+    const unknownCoreTargetWarning = getUnknownCoreVariationTargetWarning(resolvedTargetBlockName);
     assertCoreVariationSlugIsNotRegistryIndex(variationSlug);
     assertCoreVariationDoesNotExist(workspace.projectDir, resolvedTargetBlockName, variationSlug);
     const bootstrapPath = path.join(workspace.projectDir, `${workspace.packageName.split("/").pop() ?? workspace.packageName}.php`);
@@ -313,6 +417,9 @@ export async function runAddCoreVariationCommand({ cwd = process.cwd(), targetBl
             targetBlockName: resolvedTargetBlockName,
             variationFile: path.relative(workspace.projectDir, variationFilePath),
             variationSlug,
+            ...(unknownCoreTargetWarning
+                ? { warnings: [unknownCoreTargetWarning] }
+                : {}),
         };
     }
     catch (error) {

package/dist/runtime/cli-add-workspace-pattern-options.js

@@ -1,9 +1,8 @@
 import path from "node:path";
-import { assertValidGeneratedSlug, normalizeBlockSlug, } from "./cli-add-shared.js";
-import { isValidPatternThumbnailUrl, PATTERN_CATALOG_SCOPE_IDS, } from "./pattern-catalog.js";
+import { normalizeBlockSlug, } from "./cli-add-shared.js";
+import { isValidPatternThumbnailUrl, PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, } from "./pattern-catalog.js";
 import { toTitleCase } from "./string-case.js";
 const PATTERN_CONTENT_FILE_ROOT = "src/patterns/";
-const PATTERN_TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
 function assertValidPatternRelativePath(label, value, usage) {
     const normalizedPath = value.trim().replace(/\\/gu, "/");
     if (normalizedPath.length === 0 ||
@@ -41,17 +40,30 @@ function resolvePatternScope(scope) {
     }
     throw new Error(`Pattern scope must be one of: ${PATTERN_CATALOG_SCOPE_IDS.join(", ")}.`);
 }
-function normalizeOptionalSlug(label, value, usage) {
+/**
+ * Normalize and validate a raw pattern section role before catalog generation.
+ * Non-empty values are normalized with normalizeBlockSlug; valid roles start
+ * with a lowercase letter and then use lowercase letters, numbers, or hyphens.
+ *
+ * @param value Raw section-role input from CLI or programmatic callers.
+ * @returns Normalized role slug, or undefined when the input is empty.
+ * @throws When the normalized role does not match the shared section-role pattern.
+ */
+function normalizePatternSectionRole(value) {
     if (value === undefined || value.trim() === "") {
         return undefined;
     }
-    return assertValidGeneratedSlug(label, normalizeBlockSlug(value), usage);
+    const sectionRole = normalizeBlockSlug(value);
+    if (!PATTERN_SECTION_ROLE_PATTERN.test(sectionRole)) {
+        throw new Error("Pattern section role must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens. Section roles apply only with `--scope section`.");
+    }
+    return sectionRole;
 }
 function normalizePatternTags(tags) {
     const rawTags = typeof tags === "string"
         ? tags.split(",")
         : Array.isArray(tags)
-            ? [...tags]
+            ? tags.flatMap((tag) => tag.split(","))
             : [];
     const normalizedTags = rawTags
         .map((tag) => normalizeBlockSlug(tag))
@@ -91,12 +103,12 @@ function resolvePatternContentFile(patternSlug, patternScope, contentFile) {
  */
 export function resolvePatternCatalogOptions(patternSlug, options) {
     const patternScope = resolvePatternScope(options.patternScope);
-    const sectionRole = normalizeOptionalSlug("Pattern section role", options.sectionRole, "wp-typia add pattern <name> --scope section --section-role <role>");
+    const sectionRole = normalizePatternSectionRole(options.sectionRole);
     if (patternScope === "section" && !sectionRole) {
-        throw new Error("`wp-typia add pattern --scope section` requires --section-role <role>.");
+        throw new Error("`wp-typia add pattern --scope section` requires --section-role <role> because section-scoped patterns need a typed catalog section role.");
     }
     if (patternScope !== "section" && sectionRole) {
-        throw new Error("`--section-role` requires `--scope section`.");
+        throw new Error("`--section-role` only applies with `--scope section`. Use `--scope section --section-role <role>` or omit `--section-role` for full patterns.");
     }
     const title = options.catalogTitle && options.catalogTitle.trim() !== ""
         ? options.catalogTitle.trim()

package/dist/runtime/cli-add.d.ts

@@ -7,7 +7,7 @@
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, PATTERN_CATALOG_SCOPE_IDS, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, normalizeBlockSlug, PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 export type { AddBlockTemplateId, AddKindId, EditorPluginSlotId, PatternCatalogScope, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddCoreVariationCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddIntegrationEnvCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";

package/dist/runtime/cli-add.js

@@ -7,7 +7,7 @@
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, PATTERN_CATALOG_SCOPE_IDS, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, normalizeBlockSlug, PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddCoreVariationCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddIntegrationEnvCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
 export { getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, } from "./workspace-inventory.js";

package/dist/runtime/cli-help.js

@@ -27,7 +27,7 @@ export function formatHelpText() {
   wp-typia add variation <name> --block <block-slug>
   wp-typia add style <name> --block <block-slug>
   wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug>
-  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--tags <tag,...>] [--thumbnail-url <url>]
+  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>] [--tag <tag>...] [--thumbnail-url <url>]
   wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--from-post-meta|--post-meta <post-meta> [--meta-path <field>]]
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <method[,method...]>]
   wp-typia add rest-resource <name> --manual [--namespace <vendor/v1>] [--method <GET|POST|PUT|PATCH|DELETE>] [--auth <public|authenticated|public-write-protected>] [--path <route-pattern>|--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--query-type <Type>] [--body-type <Type>] [--response-type <Type>] [--secret-field <field>] [--secret-state-field|--secret-has-value-field <field>] [--secret-preserve-on-empty <true|false>]
@@ -56,6 +56,7 @@ Notes:
   Use \`--template workspace\` as shorthand for \`@wp-typia/create-workspace-template\`, the official empty workspace scaffold behind \`wp-typia add ...\`.
   Use \`--profile plugin-qa\` with \`--template workspace\` when a plugin needs local wp-env smoke checks, \`.env.example\`, and release zip scripts from day one; omit it for the minimal workspace shell.
   Interactive add flows let you choose a template when \`--template\` is omitted; non-interactive runs default to \`basic\`.
+  Unknown \`core/*\` targets for \`add core-variation\` warn instead of failing so newer WordPress core blocks remain scaffoldable; third-party namespaces are allowed without local discovery.
   \`add admin-view\` scaffolds an opt-in DataViews-powered WordPress admin screen under \`src/admin-views/\`.
   Pass \`--source rest-resource:<slug>\` to reuse a list-capable REST resource.
   Pass \`--source core-data:postType/post\` or \`--source core-data:taxonomy/category\` to bind a WordPress-owned entity collection.
@@ -67,7 +68,7 @@ Notes:
   \`add variation\` uses an existing workspace block from \`scripts/block-config.ts\`.
   \`add style\` registers a Block Styles option for an existing generated block.
   \`add transform\` adds a block-to-block transform into an existing generated block.
-  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\`.
+  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\`; pass \`--catalog-title "Hero Photo"\` to override the generated catalog title, pass \`--tags hero,landing\` for a comma-separated tag list, and repeat \`--tag hero --tag landing\` for single tag values.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`; pass \`--block\` and \`--attribute\` together to declare a bindable generated-block attribute. Pass \`--from-post-meta\` or \`--post-meta\` to back the source from a typed post-meta contract and \`--meta-path\` to choose its default top-level field.
   \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`.
   \`add rest-resource --manual\` tracks an external/provider REST route with typed schemas, OpenAPI, clients, and drift checks without generating PHP route/controller files while still allowing route-owner metadata such as permission callbacks and controller classes. Settings contracts can add \`--secret-field\` plus \`--secret-preserve-on-empty\` to model write-only credentials and preserve blank submissions.

package/dist/runtime/index.d.ts

@@ -40,6 +40,6 @@ export { EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, pruneExternalTemplateCache, } fro
 export type { ExternalTemplateCachePruneOptions, ExternalTemplateCachePruneResult, } from "./template-source-cache.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
 export { createReadlinePrompt, createDoctorRunSummary, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorExitFailureChecks, getDoctorExitFailureDetailLines, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddCoreVariationCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddPostMetaCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
-export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, formatPatternCatalogDiagnostics, PATTERN_CATALOG_SCOPE_IDS, resolvePatternCatalogContentFile, validatePatternCatalog, } from "./pattern-catalog.js";
+export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, formatPatternCatalogDiagnostics, PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, resolvePatternCatalogContentFile, validatePatternCatalog, } from "./pattern-catalog.js";
 export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, DoctorCheck, DoctorCheckScope, DoctorExitPolicy, DoctorFailureSummary, DoctorRunSummary, EditorPluginSlotId, HookedBlockPositionId, ReadlinePrompt, WorkspaceBlockSelectOption, } from "./cli-core.js";
 export type { PatternCatalogDiagnostic, PatternCatalogDiagnosticCode, PatternCatalogDiagnosticSeverity, PatternCatalogEntry, PatternCatalogScope, PatternCatalogSectionRoleConvention, PatternCatalogSectionRoleMatch, PatternCatalogValidationOptions, PatternCatalogValidationResult, } from "./pattern-catalog.js";

package/dist/runtime/index.js

@@ -31,4 +31,4 @@ export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOpti
 export { EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, pruneExternalTemplateCache, } from "./template-source-cache.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
 export { createReadlinePrompt, createDoctorRunSummary, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorExitFailureChecks, getDoctorExitFailureDetailLines, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddCoreVariationCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddPostMetaCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
-export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, formatPatternCatalogDiagnostics, PATTERN_CATALOG_SCOPE_IDS, resolvePatternCatalogContentFile, validatePatternCatalog, } from "./pattern-catalog.js";
+export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, formatPatternCatalogDiagnostics, PATTERN_CATALOG_SCOPE_IDS, PATTERN_SECTION_ROLE_PATTERN, PATTERN_TAG_PATTERN, resolvePatternCatalogContentFile, validatePatternCatalog, } from "./pattern-catalog.js";

package/dist/runtime/json-utils.d.ts

@@ -4,11 +4,8 @@
  * 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.
+ * in-memory clones, subprocess output, test fixtures, and generated workspace
+ * script templates that embed their own path-aware parse handling.
  *
  * This module keeps `cloneJsonValue` local instead of re-exporting the
  * block-runtime helper so Bunli CLI bundles that only need project-tools JSON

package/dist/runtime/json-utils.js

@@ -6,11 +6,8 @@ import { promises as fsp } from "node:fs";
  * 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.
+ * in-memory clones, subprocess output, test fixtures, and generated workspace
+ * script templates that embed their own path-aware parse handling.
  *
  * This module keeps `cloneJsonValue` local instead of re-exporting the
  * block-runtime helper so Bunli CLI bundles that only need project-tools JSON

package/dist/runtime/package-versions.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { getOptionalNodeErrorCode } from './fs-async.js';
+import { safeJsonParse } from './json-utils.js';
 import { PROJECT_TOOLS_PACKAGE_ROOT } from './template-registry.js';
 const require = createRequire(import.meta.url);
 const DEFAULT_VERSION_RANGE = '^0.0.0';
@@ -93,12 +94,10 @@ function readPackageManifest(location) {
     if (!location.packageJsonPath || location.source === null) {
         return null;
     }
-    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)}`);
-    }
+    return safeJsonParse(location.source, {
+        context: 'package version manifest',
+        filePath: location.packageJsonPath,
+    });
 }
 function tryReadPackageManifest(location) {
     if (!location) {

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

@@ -0,0 +1,101 @@
+import { type ParsedBlockPatternBlock } from "@wp-typia/block-runtime/metadata-core";
+import type { PatternCatalogDiagnostic, PatternCatalogEntry } from "./pattern-catalog.js";
+/**
+ * Validates section role slugs used by pattern manifests and content markers.
+ */
+export declare const PATTERN_SECTION_ROLE_PATTERN: RegExp;
+/**
+ * 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[];
+};
+/**
+ * Fully resolved section-role marker convention with its compiled class matcher.
+ */
+export type NormalizedPatternCatalogSectionRoleConvention = Required<PatternCatalogSectionRoleConvention> & {
+    /**
+     * Compiled matcher for role class tokens produced from `roleClassNamePattern`.
+     */
+    roleClassNamePatternRegExp: RegExp;
+};
+/**
+ * Resolve a section-role convention and compile its class-token matcher.
+ *
+ * @param convention Optional marker convention override.
+ * @returns A fully populated convention ready for repeated block traversal.
+ * @throws When `roleClassNamePattern` does not contain exactly one `{role}` placeholder.
+ */
+export declare function normalizePatternCatalogSectionRoleConvention(convention?: PatternCatalogSectionRoleConvention): NormalizedPatternCatalogSectionRoleConvention;
+/**
+ * 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[];
+/**
+ * Build the known valid section-role set from pattern catalog entries.
+ *
+ * @param patterns Catalog entries that may declare a `sectionRole`.
+ * @returns Valid section role slugs declared by the catalog.
+ */
+export declare function collectKnownPatternSectionRoles(patterns: readonly Pick<PatternCatalogEntry, "sectionRole">[]): ReadonlySet<string>;
+/**
+ * Validate serialized pattern content against the catalog section-role rules.
+ *
+ * @param options Pattern content, marker convention, known roles, and diagnostic context.
+ * @returns Diagnostics for invalid, missing, mismatched, unknown, or duplicate section-role markers.
+ */
+export declare function validatePatternContentSectionRoles({ content, contentFile, convention, knownSectionRoles, label, pattern, }: {
+    content: string;
+    contentFile: string;
+    convention: NormalizedPatternCatalogSectionRoleConvention;
+    knownSectionRoles: ReadonlySet<string>;
+    label: string;
+    pattern: PatternCatalogEntry;
+}): PatternCatalogDiagnostic[];

package/dist/runtime/pattern-catalog-section-roles.js

@@ -0,0 +1,276 @@
+import { validateBlockPatternContentNesting, } from "@wp-typia/block-runtime/metadata-core";
+/**
+ * Validates section role slugs used by pattern manifests and content markers.
+ */
+export const PATTERN_SECTION_ROLE_PATTERN = /^[a-z][a-z0-9-]*$/u;
+const DEFAULT_SECTION_ROLE_CONVENTION = {
+    baseClassName: "section",
+    requireUniqueFullPatternRoles: false,
+    roleAttributePaths: ["metadata.sectionRole"],
+    roleClassNamePattern: "section--{role}",
+    wrapperBlockName: "core/group",
+};
+function createPatternCatalogDiagnostic(diagnostic) {
+    return diagnostic;
+}
+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");
+}
+/**
+ * Resolve a section-role convention and compile its class-token matcher.
+ *
+ * @param convention Optional marker convention override.
+ * @returns A fully populated convention ready for repeated block traversal.
+ * @throws When `roleClassNamePattern` does not contain exactly one `{role}` placeholder.
+ */
+export function normalizePatternCatalogSectionRoleConvention(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 = extractPatternSectionRolesFromNormalizedAttributes(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 = normalizePatternCatalogSectionRoleConvention(convention);
+    return extractPatternSectionRolesFromNormalizedAttributes(attributes, normalized);
+}
+function extractPatternSectionRolesFromNormalizedAttributes(attributes, normalized) {
+    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, normalizePatternCatalogSectionRoleConvention(convention));
+}
+/**
+ * Build the known valid section-role set from pattern catalog entries.
+ *
+ * @param patterns Catalog entries that may declare a `sectionRole`.
+ * @returns Valid section role slugs declared by the catalog.
+ */
+export function collectKnownPatternSectionRoles(patterns) {
+    return new Set(patterns
+        .map((pattern) => pattern.sectionRole)
+        .filter((sectionRole) => typeof sectionRole === "string" &&
+        PATTERN_SECTION_ROLE_PATTERN.test(sectionRole)));
+}
+/**
+ * Validate serialized pattern content against the catalog section-role rules.
+ *
+ * @param options Pattern content, marker convention, known roles, and diagnostic context.
+ * @returns Diagnostics for invalid, missing, mismatched, unknown, or duplicate section-role markers.
+ */
+export 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;
+}

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

@@ -1,4 +1,6 @@
-import { type ParsedBlockPatternBlock } from "@wp-typia/block-runtime/metadata-core";
+import type { PatternCatalogSectionRoleConvention } from "./pattern-catalog-section-roles.js";
+export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, PATTERN_SECTION_ROLE_PATTERN, } from "./pattern-catalog-section-roles.js";
+export type { PatternCatalogSectionRoleConvention, PatternCatalogSectionRoleMatch, } from "./pattern-catalog-section-roles.js";
 export declare const PATTERN_CATALOG_SCOPE_IDS: readonly ["full", "section"];
 export type PatternCatalogScope = (typeof PATTERN_CATALOG_SCOPE_IDS)[number];
 export type PatternCatalogEntry = {
@@ -19,46 +21,6 @@ export type PatternCatalogDiagnostic = {
     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
@@ -74,23 +36,7 @@ export type PatternCatalogValidationResult = {
     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[];
+export declare const PATTERN_TAG_PATTERN: RegExp;
 /**
  * Validate pattern thumbnail references with the same URL/path rules used by
  * catalog diagnostics and `wp-typia add pattern`.

package/dist/runtime/pattern-catalog.js

@@ -1,18 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
-import { validateBlockPatternContentNesting, } from "@wp-typia/block-runtime/metadata-core";
+import { PATTERN_SECTION_ROLE_PATTERN, collectKnownPatternSectionRoles, normalizePatternCatalogSectionRoleConvention, validatePatternContentSectionRoles, } from "./pattern-catalog-section-roles.js";
+export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, PATTERN_SECTION_ROLE_PATTERN, } from "./pattern-catalog-section-roles.js";
 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;
+export 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;
 }
@@ -37,146 +30,6 @@ function isPatternContentFilePath(value) {
     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`.
@@ -199,105 +52,6 @@ export function isValidPatternThumbnailUrl(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`.
  *
@@ -316,7 +70,7 @@ export function validatePatternCatalog(patterns, options = {}) {
     let sectionRoleConvention = null;
     if (options.sectionRoleConvention !== false) {
         try {
-            sectionRoleConvention = normalizeSectionRoleConvention(options.sectionRoleConvention);
+            sectionRoleConvention = normalizePatternCatalogSectionRoleConvention(options.sectionRoleConvention);
         }
         catch (error) {
             diagnostics.push(createPatternCatalogDiagnostic({
@@ -326,7 +80,7 @@ export function validatePatternCatalog(patterns, options = {}) {
             }));
         }
     }
-    const knownSectionRoles = createKnownSectionRoleSet(patterns);
+    const knownSectionRoles = collectKnownPatternSectionRoles(patterns);
     for (const [index, pattern] of patterns.entries()) {
         const label = pattern.slug || `PATTERNS[${index}]`;
         if (!PATTERN_SLUG_PATTERN.test(pattern.slug)) {

package/dist/runtime/template-source-cache-markers.js

@@ -1,3 +1,4 @@
+import { safeJsonParse } from './json-utils.js';
 /**
  * Marker file written after a cache entry is fully populated.
  */
@@ -41,7 +42,9 @@ export function sanitizeExternalTemplateCacheMetadata(metadata) {
 export function parseExternalTemplateCacheEntryMarker(markerText) {
     let marker;
     try {
-        marker = JSON.parse(markerText);
+        marker = safeJsonParse(markerText, {
+            context: 'external template cache entry marker',
+        });
     }
     catch {
         return null;
@@ -78,7 +81,9 @@ export function isExternalTemplateCacheEntryFreshForTtl(createdAtMs, nowMs, ttlM
 export function parseExternalTemplateCachePruneMarker(markerText) {
     let marker;
     try {
-        marker = JSON.parse(markerText);
+        marker = safeJsonParse(markerText, {
+            context: 'external template cache prune marker',
+        });
     }
     catch {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -168,7 +168,7 @@
     "@wp-typia/api-client": "^0.4.5",
     "@wp-typia/block-runtime": "^0.7.0",
     "@wp-typia/rest": "^0.3.13",
-    "@wp-typia/block-types": "^0.3.0",
+    "@wp-typia/block-types": "^0.3.2",
     "mustache": "^4.2.0",
     "npm-package-arg": "^13.0.0",
     "semver": "^7.7.3",