Repository navigation
changelog
A feature release adding Mistral Vibe and OpenAI Codex agent support, a Magewire 3 skill suite contributed by the Magewire author, a Hyvä Checkout architecture skill, and nested sub-skill resources — plus reinitialize fixes that make modules created mid-session visible and stop stale-registry cache poisoning. No breaking changes.
New
-
Mistral Vibe agent support.
install --agents=mistral-vibewrites the MCP server config to.vibe/config.toml(idempotent — an existing file keeps user-managed settings, only the[[mcp_servers]]entry namedmagento-bricklayeris replaced) and compilesAGENTS.mdguidelines. Vibe reads project-scoped config from./.vibe/config.tomlautomatically, so no extra setup is needed. -
OpenAI Codex agent support.
install --agents=codexwrites the MCP server config to.codex/config.toml(idempotent — only the[mcp_servers.magento-bricklayer]section is replaced) and compilesAGENTS.mdguidelines. Note: project-scoped.codex/config.tomlrequires a recent Codex CLI and a trusted project. Gemini, Codex and Mistral Vibe shareAGENTS.md: it is written once and its footer lists every agent it serves.
Fixes
-
Modules created mid-session are now visible after
reinitialize. Component registration runs once per PHP process via Composer's autoload hook, so a fresh ObjectManager reused the staleComponentRegistrarregistry: a newapp/codemodule stayed invisible tocode-runnerand config readers, and reinitialization could regenerate merged-config caches without the module into shared cache storage. Registration globs now re-run on every (re)init, and Composer'sautoload_files.phpis re-scanned on reinit for packages installed mid-session. -
reinitializeaborts before touching shared caches when the registry is irrecoverably stale — a module enabled inconfig.phpbut not registered, or an enabled module's directory deleted. Reinit refuses with an actionable "restart the MCP server" error and keeps the previous ObjectManager instead of silently poisoning caches; sentinel-triggered auto-reinit refuses the tool call the same way rather than answering from stale state. -
reinitializeresponse is honest about registry state. Reportsregistered_componentsandnewly_registered_filesalongsidemodules_loaded, surfaces a failed module-count read asmodules_loaded_error, and awarningfield flags enabled-but-unregistered modules and registered components removed from disk. -
MagentoBootstrap::reset()now clears the sentinel-mtime snapshot and reinit stats, not just the ObjectManager and root path.
Skills
-
Magewire 3 development suite — a new
magewire-threeskill covering greenfield Magewire 3 components, Magewire V1→V3 migration, Livewire V3-style directives and events, component resolvers, snapshots, synthesizers, compiled templates, and Alpine CSP integration — with nested sub-skills for architecture internals, the per-component backwards-compatibility layer, application-code best practices, CSP-compatible JavaScript, theme compatibility modules, and the Portman framework-maintainer workflow. Contributed by Magewire author Willem Poortman. - Hyvä Checkout architecture and development — a central skill covering Evaluation results, primary navigation, Place Order Services, frontend payment methods and backports, layout-independent integrations, and a mandatory compatibility profile that selects Magewire V1 for checkout 1.0-1.3.*, native Magewire 3 for new components on 1.4+, or the backwards-compatibility migration track for existing V1 components. The existing API, configuration, and Magewire guides were corrected to remove component-owned order placement and direct step progression patterns.
Improvements
-
Nested sub-skill resources. A skill directory can now contain focused topic sub-directories, served via the new
magento://skills/{name}/{topic}resource template. Previously only flatmagento://skills/{name}URIs resolved. -
Frontmatter stripped from skill resources. An optional YAML frontmatter block in a
SKILL.mdis removed before the content is served overresources/read, matchingdevelopment-contextbehavior. Path segments containing..are rejected.
Counts: 84 tools (unchanged), 21 tool classes, 36 runtime-configurable tools, 3 reference resources.
A feature release adding an order-creation tool, plus code-runner correctness fixes, a canonical .phtml template convention, and community/contribution docs. No breaking changes.
New tools (hidden, discover via search-tools)
-
order-create— build and place an order: line items by SKU, one billing/shipping address, chosen shipping and payment method. Supports all default product types (configurable, grouped, bundle, downloadable) with option data given by human-friendly codes/labels/SKUs, product custom options, existing-customer orders viacustomerId(0 = guest), and virtual/downloadable-only orders (shipping skipped automatically). Like other order-mutating tools it is disabled by default and blocked in production; enable viatools.order-create.enabled=truein.bricklayer.json.
Fixes
-
code-runner: a timeout no longer kills the MCP server. The execution limit is now enforced by a catchable wall-clock SIGALRM (wherepcntlis available) instead ofset_time_limit()'s uncatchable fatal: on timeout the transaction rolls back and the call returns a normal error (timed_out: true) — the server keeps running and session state survives. Wall-clock also means stalled DB queries now count toward the limit. -
code-runner: fatals now report instead of silently dropping the connection. A shutdown hook answers the in-flight request with a JSON-RPC tool error naming the fatal before the process dies, so the agent sees the real cause rather thanConnection closed. -
code-runner: define-mode helpers no longer fatal on the second use. Functions are declared once into the global namespace at define time (behind afunction_existsguard); syntax errors surface at define time, and redefining an already-declared name returns awarninginstead of fataling. -
code-runner:timeout=0no longer disables the execution limit. The effective timeout is floored at 1s — previouslytimeout<=0reachedset_time_limit(0), which means unlimited. -
database-query:SELECT(...)is no longer rejected. The SELECT guard now uses a word boundary, soSELECT(1) AS xpasses whileSELECTED...is still rejected. -
code-runner: state reset now clears repository identity maps (product, category,CustomerRegistry), so changes made outside the MCP process are no longer hidden by stale cached entities. -
code-runner: clearer message when writes are blocked by config. Ifallow_write=trueis requested but disabled in.bricklayer.json, the response names the config key to enable (write_blocked_by_config: true) instead of suggesting a flag that was already set.
Guidelines & generated code
-
Standard
.phtmltemplate convention (Luma and Hyvä): required header order (declare→use→@var) and clear escaping rules ($escaper, or/* @noEscape */for safe non-HTML output).generate-controlleroutput and all guideline examples now follow it.
Docs
- Added
CONTRIBUTING.md,CODE_OF_CONDUCT.md, andSECURITY.md.
Counts: 84 tools (was 83), 21 tool classes, 36 runtime-configurable tools, 3 reference resources.
A feature release adding runtime introspection for the view layer and message-queue wiring — three read-only tools that surface resolved/merged state no single source file shows. No breaking changes.
New tools (hidden, discover via search-tools)
-
layout-inspect— resolve a layout handle into its runtime-merged block/container tree (merged across every module and the active theme), showing appliedreferenceBlock/referenceContainer/move/removedirectives, declared and theme-resolved.phtmltemplate paths, and the page layout. Omit the handle to list every registered handle for an area. Config-gated, enabled by default. -
ui-component-inspect— resolve an admin grid/form UI component's runtime-merged configuration (component tree, data source, columns/fieldsets, child components) merged across modules. Config-gated, enabled by default. -
message-queue-inspect— the runtime-merged consumer → topic → queue → exchange topology with publisher and handler bindings, assembled acrosscommunication.xml,queue_consumer.xml,queue_topology.xml, andqueue_publisher.xml. Ungated.
Removed
- The static
layouts_referenceMCP resource (a hand-maintained handle catalogue) is retired in favour oflayout-inspect's runtime list mode — registered handles are now read from the live install.
Counts: 83 tools (was 80), 21 tool classes, 35 runtime-configurable tools, 3 reference resources.
-
code-runnerbare helper functions now work in the PsySH runtime —get(),create(),repo(),config(),query(), andrunLog()(documented incode-runner-help) previously fataled withCall to undefined function get()under PsySH, where they existed only as the$get/$create/… scope closures. Both the bare and$-prefixed forms now work in both runtimes and stay bound to the live ObjectManager across calls. - Fixed a latent guard bug in the
evalfallback where the helper-functionfunction_exists()check resolved against the wrong namespace, which could fatally re-declare helpers on a second invocation in a long-lived process.
A code-audit release: correctness and security fixes, code-runner now uses PsySH as intended, and duplicated internal logic consolidated. No breaking changes.
Security & safety
-
Environment-variable tool overrides now work for every tool.
BRICKLAYER_TOOLS_*settings were silently ignored for hyphenated tools (e.g.code-runner,product-delete), so disabling a tool via an env var had no effect. Use the full-path form, e.g.BRICKLAYER_TOOLS_CODE_RUNNER_ENABLED=false. -
code-runneris now reliably blocked in production even when the deploy mode can't be read (fails closed instead of open).
Fixes
-
code-runneractually runs through PsySH when installed — it previously fell back to a basicevalengine on every call while wrongly reporting "PsySH not available". Responses now report the activeruntime(psyshoreval). -
diagnose-errorcounts error history from the log the error was actually found in, instead of alwaysexception.log. - GraphQL introspection labels input types correctly and returns type descriptions (both were broken).
-
database-schemanow respects its own enable/disable setting (it was tied todatabase-query). -
The
mcpcommand honors--magento-rooton systems withoutpcntl. - Smaller fixes: safer log-file handling, accurate text truncation, recursive module validation, correct config-write success reporting, dynamic (non-hardcoded) tool/category counts, data-URI image type detection.
Internal (no behavior change)
- Consolidated duplicated logic — error responses, pagination, sensitive-value masking, time parsing, command setup, and log/markdown scanning — into shared traits and helpers.
- Wired up the previously-orphaned PhpStorm config writer, so
installnow generates.idea/mcp.json.
-
New guideline: Pool pattern (
patterns/pool.md) — DI-based strategy resolution with extensible array injection, replacing if/else branching on type identifiers. Covers third-party extensibility and chain of responsibility with sortOrder. -
New guideline: Value Object / DTO (
patterns/value-object.md) — Immutable data carriers withpublic readonlyproperties,fromJson()/toJson()serialization for JSON columns, and comparison with Data Interfaces. -
New guideline: Context Object (
patterns/context-object.md) — Bundling repeated request-scoped parameters (customerId, storeId, currencyCode) into a single immutable object with a Builder. -
Updated: Plugin pattern — Added "Plugin Chain on Repositories" section showing how to chain multiple
beforeSaveplugins with sortOrder for cross-cutting concerns. -
Updated: Coding Standards — Added "Constants as Final Classes" section for grouping enum-like constants in
final classinstead of interfaces.
- Added Symfony Console 7 compatibility (
symfony/console: ^5.4 || ^6.0 || ^7.0).
-
Project-local overrides — New
.bricklayer/directory at the Magento root lets projects add or replace bundled content without forking the package:-
project-context.md— appended to every generated agent file under a## Project-Specific Contextheading -
decision-matrix.md— extra rows merged into the "Before Modifying" table -
guidelines/{path}.md— override bundled guidelines by matching relative path, or add new sections with no bundled counterpart -
skills/{category}/SKILL.md— override bundled skills, or add new local-only categories directly callable viadevelopment-context category={directory} - Optional YAML frontmatter (
name:,description:) on local SKILL.md files for rich display; stripped before content is returned to agents - Local entries tagged
[Project]insearch-docsresults
-
-
bricklayer updatenow reports applied local overrides/additions and the number of local docs-index entries -
bricklayer initnow creates.bricklayer/automatically - New
LocalOverrideHelperutility — shared static helpers for YAML frontmatter parsing and stripping, used byGuidelinesCompiler,ContextTools, andSearchTools -
GuidelinesCompiler,ContextTools, andSearchToolsconstructors now accept optional$magentoRoot/$packageRootfor testability - 29 new unit tests across
LocalOverridesTest,LocalGuidelineAdditionsTest,LocalSkillResolutionTest,LocalDocsIndexTest— suite total: 353 tests, 999 assertions - Documentation audit — removed stale
--config-only/--docs-onlyflag references (neither exists inUpdateCommand), removed stale "documentation index" phrasing, added missingverifycommand documentation to the README, correctedcontributing.mdclass counts (19 tool classes, 5 resource providers), added newconfiguration/local-overrides.mdwiki page
- Fixed array_map error in InstallCommand when a single AI agent is selected
- Added ArrayManager for checkout jsLayout manipulation in the LayoutProcessor skill example
- New
check-classTier 1 tool — combined plugin-list, di-configuration, and preference-list in one call - Behavioral triggers in server instructions — agents are told WHY to check runtime state before modifying code
- "Before Modifying Magento Code" decision matrix in generated agent guidelines (CLAUDE.md, .cursorrules, etc.)
-
_skill_hintin introspection tool responses — points agents to the relevantdevelopment-contextcategory -
_next_stepsindevelopment-contextresponses — suggests introspection tools to call before writing code - Rewrote Tier 1 tool descriptions with "Check BEFORE..." behavioral triggers
- Removed generic architecture section from generated agent guidelines
- Simplified Context Quick Reference to point at the new decision matrix
- README rewritten with "How Agents Use Bricklayer" section and check→learn→write workflow
- Fixed preamble duplication in
code-runnermode=define - Fixed
$modevariable shadowing inCodeRunnerTools - Added
diagnose-performanceto search indexes - Added config gating to
diagnose-performance - Removed phantom Integration test suite from
phpunit.xml.dist - Reduced coupling in
PerformanceTools - Added unit tests for
FiltersFields,RequiresMagento, andToolScanner
- Config staleness detection via
.bricklayer.jsonmtime tracking with automatic hot reload - Reusable code-runner functions (
mode=define) persisting across calls (max 20 per session) - New
diagnose-performancetool with 6 checks: indexes, cache, flat-tables, cron-backlog, config, queries - Updated
code-runner-helpwith mode parameter documentation
- Improved test coverage
-
Security: Fixed
isProductionMode()to fail closed when bootstrap unavailable - Tightened MCP SDK version constraint to
^0.3 || ^1.0 - Improved
VerifyCommandexception parser testing - Clarified
graphql-inspectresolver target documentation
-
reinitializeMCP tool for ObjectManager rebuild - Automatic staleness detection via sentinel file mtime tracking
- Progressive tool disclosure (tier 1 visible, tier 2 discoverable)
- Compressed tool descriptions to 80 words max
- Tool consolidation: 5 GraphQL tools, 4 log tools, 5 system tools merged
- Pagination metadata (
has_more) on all list tools - Context-aware hints (
_hintfield) in tool responses - Pruned guidelines duplication, compressed server instructions
- Standalone
magewiredevelopment-context category
-
Security: Fixed
requireNonProductionbypass, SQL injection inDatabaseTools - File overwrite detection and
forceparameter for code generation - Config enforcement for log tools (
max_lines) - New unit tests for
ChecksConfigandConfigInitializer
- Production safety system with per-tool enable/disable
-
ChecksConfigtrait for all tool classes - Production mode blocking for destructive and code generation tools
- Sensitive config path masking in database queries
- Path traversal protection in code generation
-
bricklayer initcommand for.bricklayer.jsongeneration
-
ToolRegistrysingleton for centralized tool management - Extracted shared traits:
FiltersFields,SecureArea,RequiresMagento - Dynamic version reading from
composer.json - Standardized error responses across all tools
- MCP efficiency features:
batch-execute,count_only,fields,verbosity,truncation -
search-toolsfor tool discovery - DI inspection tools:
configuration-list,di-configuration,plugin-list,event-list,preference-list -
eav-entity-typestool - Improved
code-runnerwithcode-runner-helpcompanion
- Verify command for installation verification
- GraphQL method fixes
- Diagnostic tool unit tests
- Improved code-runner and log reading
- Auto-discovery for tools, guidelines, and skills
-
ToolScannerfor automatic tool detection - Dynamic context category loading
- Enhanced code-runner with helpers
- Codebase simplification and error diagnostic improvements
-
diagnose-errortool with exception parser -
ReadsLogFilesconcern - Route and search-docs fixes
- Hooli agent support
- Skills split into smaller chunks for reduced context usage
-
development-contexttool - Coding standards guidelines
- Hyva theme, UI components, and checkout knowledge
- Interactive install, checkout/payment/theme skills
- Initial release
Getting Started
Architecture
Tools Reference
- Overview (84 Tools)
- Introspection
- Catalog
- Orders
- Customers
- Database
- Logs & Diagnostics
- GraphQL
- Development
Configuration
Guidelines & Skills
Code Generation
Diagnostics
Security