Feature : Add support for building blocks in theme updates

[sagarjadhav]

Description

Improves block development tooling by adding stricter CLI validation, fixing block registration edge cases, introducing cross-platform block build scripts, and updating block development documentation.

Technical Details

bin/create-block.js — Rewritten

• Replaced execSync with spawnSync to pass arguments as an array, avoiding shell interpolation and making argument handling safer and more predictable
• Replaced the loose parseUserInputArgs string-building approach with a stricter parseArgs() helper that uses a Set to track seen keys and a Map for defaults, preventing duplicate flags
• Added block name validation — must start and end with a lowercase letter or number, no leading/trailing hyphens (/^[a-z0-9][a-z0-9-]*[a-z0-9]$/)
• Prevents accidental overwriting of existing blocks by failing early if the target block directory already exists
• Added printUsage() helper shown on validation errors
• Handles the case where spawnSync exits due to a signal (result.status === null), reporting the signal name instead of a misleading exit code
• Removed defaults for --title, --category, --icon, --keywords, and --short-description since these values should be explicitly defined per block

class-blocks.php — Bug fixes

• Fixed an issue where _-prefixed blocks were not excluded correctly. Because the path contained a leading /, strpos() returned 1 instead of 0, causing the prefix check to fail. The fix uses basename() to reliably extract the block directory name
• Added an is_dir() guard before filesystem operations, preventing errors on fresh clones before a build has run
• Added function_exists( 'wp_register_block_metadata_collection' ) guard — this function was introduced in WordPress 6.7; without the guard it would fatal on older versions
• Ensures glob() failures are handled safely by falling back to an empty array when it returns false
• Removed redundant untrailingslashit() wrapper — get_template_directory() already returns a path without a trailing slash
• Changed setup_hooks() visibility from public to private — it is only called from __construct

package.json — Updated

• Refactored block build commands into Node wrappers to allow filesystem guards and cross-platform compatibility
• build:blocks — replaced direct wp-scripts call with node ./bin/build-blocks.js
• build:block-manifest — replaced Unix-only shell command with node ./bin/build-block-manifest.js (the previous command relied on find, grep, and rm -f which do not work on Windows)
• start:blocks — replaced direct wp-scripts call with node ./bin/start-blocks.js
• lint:css:fix — removed duplicate ./assets/src argument (path already included via npm run lint:css)
• lint:js:fix — removed duplicate ./assets/src argument (same issue)
• @wordpress/interactivity — moved from dependencies to devDependencies since it is bundled during build and not required at runtime
• minimatch override — changed from pinned 3.1.3 to ^3.1.3 for consistency with other override entries

bin/build-blocks.js — New file

Prevents webpack from running when no block sources exist. Checks for at least one non-_-prefixed directory in assets/src/blocks/ before invoking webpack. If none found, exits silently with code 0 — preventing an empty assets/build/blocks/ directory from being created on a fresh clone.

bin/build-block-manifest.js — New file

Wraps wp-scripts build-blocks-manifest. Checks for at least one compiled block.json inside assets/build/blocks/ before running. If none found, exits silently with code 0 — preventing build:prod from failing on fresh clones or CI environments.

bin/start-blocks.js — New file

Same guard as build-blocks.js but for watch mode. Skips wp-scripts start if no buildable block sources exist.

docs/blocks-guide.md — Rewritten

• Added Block Naming Rules section with valid/invalid examples
• Added explanation of the -- npm argument separator
• Replaced parameter list with a structured table including defaults column
• Clarified --variant and --namespace are pre-configured defaults, only need to be passed to override
• Marked --title as (Recommended) instead of just optional
• Replaced deprecated block category common with text
• Added Development Workflow section covering npm run start watch mode
• Added Troubleshooting table covering all CLI error states and the Windows shell script failure
• Updated block directory structure to reflect actual scaffolded files (edit.js, save.js, .scss)
• Added note that build:blocks skips and creates no empty folder when no blocks exist
• Updated automatic registration section to accurately describe the manifest-based approach

Checklist

• Block name validation enforced in CLI
• Duplicate block guard prevents silent overwrites
• _ prefix exclusion bug fixed in block registration
• WordPress 6.7 compatibility guard for wp_register_block_metadata_collection()
• No empty assets/build/blocks/ folder on fresh clone
• build:block-manifest works on Windows
• lint:css:fix and lint:js:fix duplicate path arguments fixed
• Documentation fully updated

Screenshots

N/A — CLI tooling and PHP registration only, no UI changes.

To-do

• Consider switching from spawnSync to spawn in start-blocks.js if non-blocking watch behavior is needed.

[nani-samireddy]

Everything else LGTM