feat(theme): site-to-theme assembly + blocks-engine npm packaging#346
Merged
Conversation
… export catalog/recipe-table primitives
…Markup + validateBlockContract + walkBlocks + core-block-attrs snapshot)
…ockContract (faithful to DLA)
When --out is omitted, the theme command writes to ./_block-theme in the current directory and exits asking for --out if that directory already exists, so a stray _block-theme/ is never silently overwritten.
## Summary
Rewrite the blocks-engine package README into a clean top-to-bottom onboarding flow: a scoped header, dedicated Install and Quick Start sections, table-formatted CLI reference, and a JavaScript API section.
## Why
The previous README led with awkward section names ("Start Here", "Which Do I Use?") and buried install instructions. Its exported-symbols list was also stale — it omitted the theme exports (siteToTheme, writeTheme, lintThemeJson) and related types that src/index.ts actually ships.
## How
Added Install and Quick Start sections, converted the CLI commands/options prose into tables, replaced the bare export dump with a use-case table plus a programmatic siteToTheme example, documented the ./theme and ./wp subpath exports, broke the Worker Pool prose into labeled subsections, and added a License section. All API details verified against cli.ts, index.ts, and theme/types.ts.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01598tUQPYKEXZnknf2mgeyx
## Summary Adds the packaging metadata and license file needed to publish @automattic/blocks-engine to the public npm registry. ## Why The scoped package had no publish configuration, so npm would default to a private (paid-scope) publish and a misrouted registry. The declared GPL-3.0-or-later license also shipped no LICENSE file, since npm only includes a LICENSE that lives inside the package directory. ## How - Add publishConfig with access: public and the public npmjs.org registry so a plain `npm publish` targets the right place and publishes the scope publicly. - Add a prepublishOnly script that runs the tsup build, so the gitignored dist is always freshly built before publish. - Vendor a copy of the GPL-3.0 LICENSE into the package so it ships in the tarball. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XaSpm1VM21MrJWWRe3ujbs
## Summary Wires up monorepo-consistent version tagging for @automattic/blocks-engine: a homeboy release config and an npm tag-version prefix, both producing `blocks-engine-v<version>` tags to match php-transformer and figma-transformer. ## Why blocks-engine had no release automation and no tag convention. npm version would default to bare `v<version>` tags, which collide with the monorepo's per-package tag namespace. The package also had no homeboy entry, so it couldn't be driven through the same release preflight as the sibling PHP packages. ## How - Add homeboy.json with id `blocks-engine`, package.json as the single version target, and CHANGELOG.md as the changelog target. Releases run via `homeboy release blocks-engine` and tag as `blocks-engine-v<version>`. - Set tag-version-prefix in .npmrc so any `npm version` bump also produces a correctly namespaced tag rather than a bare `v<version>`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XaSpm1VM21MrJWWRe3ujbs
## Summary Closes the DX gaps surfaced by the developer-experience review of the public package surface: a documented error-code contract, self-healing CLI errors, complete npm metadata, and contribution scaffolding. ## What changed - README: add an "Error handling" section documenting the four stable BlocksEngineError codes (alphabetized) with a try/catch example. The `code` is now an explicit part of the package contract. - CLI: introduce CliUsageError for argument-syntax mistakes (unknown option, missing srcDir, missing value, unexpected argument) and reprint usage on them, so a mistyped flag self-heals instead of printing a bare line. - package.json: add repository (with monorepo directory), homepage, bugs, and engines.node (>=20, matching CI); add a `typecheck` script (tsc --noEmit). - Add a root CONTRIBUTING.md and a .github bug-report issue template so external users have a guided path to develop and report issues. ## Testing - [x] pnpm test (334 passing, includes 2 new CLI usage-reprint tests added red-first) - [x] pnpm typecheck (tsc --noEmit, 0 errors) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XaSpm1VM21MrJWWRe3ujbs
## Summary Adds a dedicated Typecheck step (pnpm typecheck → tsc --noEmit) to the path-scoped blocks-engine workflow, so type errors fail the run early and independently of the bundler. ## How - New "Typecheck" step runs after install and before build. - Job renamed "Install, build, and test" → "Typecheck, build, and test". - Relies on the `typecheck` script added to packages/blocks-engine/package.json. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XaSpm1VM21MrJWWRe3ujbs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands
@automattic/blocks-enginefrom translation-only to translation + deterministic theme assembly, and prepares the package for its first public npm release. The engine now owns two generic, consumer-agnostic capabilities — HTML→blocks translation and static-directory→block-theme assembly — with extension seams for consumers (first being the data-liberation-agent importer). See ADR 0004, which supersedes the translation-only framing of ADR 0001.What's in here
Theme assembly (the bulk of the work)
preserve-DOMandreconstruct-sectionstrategies, plus library-parity tests.CLI
./_block-theme, with hardened path error handling.Packaging / release (this session)
publishConfig(public access, npmjs.org registry) +prepublishOnlybuild hook, and a vendored GPL-3.0 LICENSE so the tarball ships its declared license.homeboy.json(idblocks-engine,package.jsonas the version target) and an npmtag-version-prefixofblocks-engine-v, matching thephp-transformer-v*/figma-transformer-v*tag convention.