Console Laravel Package

Product Decisions This Supports

• Build vs. buy for the front-end asset pipeline. Assegai Console keeps component compilation inside the PHP application’s own CLI instead of adding a Node/Gulp/Vite orchestration layer. The 0.10.6 release strengthens this position by making the tool viable for apps with more than one component surface, which is the point where teams usually abandon homegrown tooling for a JS-native bundler.
• Bundle architecture / performance roadmap. Independent Web Component groups let you ship site.min.js and editor.min.js separately, so public pages stop paying for editor-only component weight. This is a concrete, shippable performance decision rather than a refactor: groups are opt-in via assegai.json, existing single-bundle projects are unchanged.
• Multi-surface product strategy. If the roadmap includes an admin console, embedded editor, or widget library alongside the main site, groups give each surface an explicit ownership boundary (its own entry file, manifest, esbuild graph under .cache/assegai/groups/<name>/). Group isolation rules — no overlapping source membership, no cross-group .wc.ts imports, rejection of paths escaping the workspace — encode architectural boundaries as build-time errors instead of code-review conventions.
• Deployment and release-engineering decisions. Because building a selected group leaves unselected groups’ artifacts untouched, CI can build only what changed. That enables per-surface pipelines and shorter deploys, at the cost of the application remaining responsible for including the right bundles per page. Treat this as an explicit decision to own bundle wiring in templates.
• Developer-experience investment. Watch mode now survives empty sessions, picks up additions/removals/renames (including the first component in a not-yet-existing directory), and only reports unreadable directories as errors rather than swallowing them. This is a support-ticket and onboarding-cost reduction, and it removes a class of “why didn’t my component rebuild?” confusion that erodes trust in internal tooling.
• Upgrade cadence and version risk. 0.10.6 is pre-1.0 and additive: no framework request-time changes, no migration for existing projects, PHP 8.4+ requirement unchanged. The decision it supports is “stay current on 0.10.x and pin”, not “commit to this as a stable platform dependency.”
• Toolchain consistency across a mixed-version fleet. CLI isolation means the executing Console installation’s classes stay authoritative after loading a workspace autoloader, so an older project-local Console can’t substitute incompatible classes during extension discovery. This directly supports the decision to use one global Console across many projects of differing ages, which is otherwise a recurring source of “works on my machine” failures.

When to Consider This Package

Adopt when most of the following hold:

• The application is PHP 8.4+ (Laravel or otherwise) and you want component builds driven from the same CLI and deployment path as the rest of the app, without maintaining a separate JS build stack.
• You have two or more distinct component surfaces (public site, editor, admin, embeddable widgets) and want separate bundles with enforced ownership boundaries. This is the capability 0.10.6 specifically unlocks; before it, the case was weaker.
• You want hot reload and watch-mode behavior that handles real editing patterns — new files, renames, deletions, initially empty directories — without restarting the watcher.
• You run a global Console across multiple projects and need version isolation between the CLI and project-local installs.
• Your team accepts explicit, non-magical configuration: sources are literal workspace-relative directories or .wc.ts files, and the app — not the tool — decides which bundle each page loads.
• You can live with pre-1.0 API movement and want a small, auditable dependency surface.

Look elsewhere when any of the following apply:

• Windows is a first-class developer platform. The release notes state Windows was not tested; validation covers Ubuntu 24.04 on PHP 8.4.26/8.5.11 plus focused macOS checks. Treat Windows support as unverified and budget for it.
• You need glob patterns for source selection. They are explicitly unsupported; every source path must be enumerated.
• You need shared component ownership across bundles. Overlapping group membership is rejected, as is importing another group’s .wc.ts. Shared ordinary TypeScript and CSS dependencies are supported, so the constraint is on components, not utilities — but if your architecture assumes shared components, this is a blocker rather than a preference.
• You need a stable, post-1.0 contract, long-term support guarantees, or a large plugin ecosystem.
• You want the build tool to also handle asset inclusion, deployment uploads, or SSR. The notes are explicit that compiler/runtime builds and deployment uploads are separate workflows.
• You are not on PHP 8.4+, or you depend on a Console version whose extension discovery behavior you have deliberately pinned against a project-local install.

How to Pitch It (Stakeholders)

For executives (one paragraph). Assegai Console 0.10.6 lets our PHP application build separate JavaScript bundles for separate parts of the product — public site, editor, admin — from one configuration file, instead of shipping one large bundle everywhere. That is a direct page-weight and load-time win on customer-facing pages, and it lets each surface ship independently. The upgrade is additive and opt-in: existing projects keep their current behavior with no migration, and there are no changes to request-time framework code. The main caveat is maturity — this is a pre-1.0 tool, and Windows developer machines are not covered by the vendor’s testing — so we should adopt it deliberately and pin the version rather than treat it as a settled platform bet.

For engineering leads. Three things matter. First, groups are a real architectural boundary: each group gets its own entry file, manifest, and esbuild dependency graph, builds are isolated so unselected groups’ artifacts are untouched, and invalid configurations — unknown groups, overlapping sources, conflicting output paths, paths escaping the workspace, cross-group component imports — fail the build rather than silently producing wrong output. Second, watch mode is now trustworthy: it detects additions, removals and renames including the first component in an absent directory, stays alive when empty, distinguishes unreadable directories from missing ones, updates per-group and root reload markers, supports --no-hot-reload, and coordinates child processes and locks so concurrent writes to the same group are prevented while different groups build in parallel. Membership polling is tied to the configured hot-reload interval; idle checks don’t read source contents or hash bundles. Third, the CLI is hardened for multi-project use: the executing Console’s classes remain authoritative after workspace autoloading, so older project-local installs can’t hijack extension discovery, and the entrypoint forwards the application’s return code when automatic exit is disabled.

Verification and residual risk to state plainly. CI passed on Ubuntu 24.04 with PHP 8.4.26 and 8.5.11: 233 passing tests, 1,073 assertions, one pre-existing skipped test, PHPStan level 8 clean, strict Composer validation passing. Regression coverage targets the exact behaviors above, including selected-group isolation, invalid ownership and paths, add/remove/rename handling, initially empty sources, CSS-only changes, reload markers, process teardown, exit statuses, and older workspace Console installs. Two honest gaps: the orchestration tests use a fake esbuild with real-esbuild group isolation verified only separately, and Windows is untested. Also note a behavioral change for existing watch users — empty watch sessions no longer exit immediately — which may affect scripts that relied on that termination. Recommended rollout: upgrade via assegai global update, confirm with assegai --version, run the existing single-bundle build to confirm no diff, then introduce one group behind the config flag and validate artifact inclusion in templates before splitting further.