Console Laravel Package

Technical Evaluation

Architecture fit. This release materially changes the package's architectural profile. As of 0.10.5 Console was a developer-facing CLI in the toolchain layer, with no path into application artifacts. 0.10.6 introduces independent Web Component groups: configured in assegai.json, built via wc:build/wc:watch, emitting JavaScript and sibling CSS into application-served paths (e.g. public/js/site.min.js), with per-group caches under .cache/assegai/groups/<name>/. Console has therefore crossed from "developer convenience" into the build and asset pipeline, with write access to application output directories, ownership of emitted artifacts, and a long-running watch process that coordinates child esbuild processes.

That is still build-time, not request-time — no framework bootstrapping, service provider, or HTTP lifecycle change — so production runtime architecture is unaffected. But blast radius is no longer "misleading tool output for a developer." A broken or misconfigured group build can now mean missing front-end assets on deployed pages. The package's identity is now dual: CLI plus asset bundler. Groups are opt-in, which contains the risk, but the assessment must treat the two capabilities as separate adoption decisions.

Integration feasibility. Low effort for the CLI upgrade itself; medium for groups. No changes to dependency constraints, installation locations, PHP floor, or entrypoints. Upgrade remains a single command plus verification. Existing projects without webComponents.groups retain single-bundle source discovery, output paths, and list JSON structure, so there is no migration.

Groups introduce a genuine configuration surface and a set of opinionated constraints that need to be evaluated against our repo layout before commitment: sources must be explicit workspace-relative directories or .wc.ts files (no glob support), source membership cannot overlap across groups, cross-group .wc.ts imports are rejected, and paths escaping the workspace are refused. Shared ordinary TypeScript and CSS remain supported. Applications remain responsible for including the emitted bundles in their pages, and compiler/runtime builds and deployment uploads remain separate workflows — Console does not take over delivery. That boundary is the right one, and it keeps integration scope bounded.

Technical risk.

• Pre-1.0 surface. Unchanged and now more consequential. At 0.10.x there is no stability guarantee, and the package now owns build configuration and emitted artifacts. SemVer permits breaking changes in a minor. Pin deliberately; re-assess at every minor and at 1.0.
• PHP 8.4+ floor. Unchanged, still the largest adoption gate relative to typical Laravel estates. Positive signal: CI now validates on PHP 8.4.26 and 8.5.11, so forward compatibility with the next PHP minor is evidenced, not assumed.
• Watch-mode behaviour change. Empty watch sessions now stay active instead of exiting immediately. This is a correct fix but a de facto behavioural break for any script, CI job, or npm/Composer hook that relied on wc:watch terminating on an empty source set. Any such caller will now hang. This is the single most likely surprise in the release and is not labelled as breaking.
• Filesystem-adjacent risk, Windows untested. Watch mode now handles directory creation/removal/rename, including the first component in an initially absent directory, and raises on unreadable directories rather than silently ignoring them. That is better behaviour but more surface. Windows remains explicitly untested, and this release is substantially more filesystem- and process-intensive than 0.10.5. The prior platform caveat is now more important, not less.
• Destructive artifact behaviour. A previously emitted group stylesheet is removed when a successful build no longer emits it. Correct for hygiene, but it is a delete inside public/ driven by build state. Pages referencing a decommissioned stylesheet will break silently at build time, not at authoring time.
• New concurrency model. Locks prevent concurrent writers to the same group while allowing different groups to build independently; one watch session coordinates and tears down its children together. This is the right design, but it introduces stale-lock and orphaned-child failure modes, particularly under SIGKILL or CI cancellation where graceful shutdown does not run.
• Validation gap. CI reports 233 passing tests, 1,073 assertions, PHPStan level 8, strict Composer validation — solid. But orchestration tests use a fake esbuild, with real-esbuild group isolation checked only separately and locally. The exact composition we would depend on (real esbuild, multiple groups, shared graph) is the least covered path.
• Prior defect class partially resolved. The 0.10.5 caveat that an older project-local Console could substitute incompatible classes during discovery is now explicitly fixed: extension discovery keeps the executing installation's classes authoritative after the workspace autoloader loads. That is a real narrowing of the known hazard. Binary shadowing via shell alias/wrapper/PATH remains undetected and should stay on the accepted-caveats list.
• Exit-code forwarding. Explicitly forwarding the application's return code when automatic exit is disabled is a quiet but valuable fix for scripted and CI use.

Key questions.

1. Is Console still only scaffolding and version hygiene for us, or are we now committing it to the asset pipeline? These are separate decisions and should be approved separately.
2. Does any script, CI job, or hook invoke wc:watch in a context where the empty-session-exits behaviour was load-bearing? Grep before rollout.
3. If we adopt groups, who owns public/js/* — Console or the application? What is the rollback if a group build deletes a stylesheet a page still references?
4. Do our component sources fit the no-glob, no-overlap, no-cross-group-import model, or does our layout depend on shared component code that groups now forbid?
5. Do we have Windows developers or Hostinger/shared-hosting targets? The answer matters more in 0.10.6 than in 0.10.5.
6. What esbuild version do we get, and how is it pinned and upgraded? It is now a transitive dependency of our front-end output.
7. Do we have long-running or cached CI environments where .cache/assegai/groups/* locks could persist between jobs?
8. Is 0.11 or 1.0 imminent? If groups are on the roadmap for us, timing adoption against the stability commitment may be cheaper.

Integration Approach

Stack fit. Good for a Laravel/PHP team, with a caveat: the CLI half remains a clean, additive developer-experience tool, while the groups half is a front-end build tool that overlaps with whatever we already use (Vite, Mix, plain esbuild). Fit must be judged per half. Adopting the CLI update does not commit us to replacing or supplementing our asset pipeline.

Migration path. CLI: no migration; upgrade and verify. Groups: greenfield and opt-in, but treat it as a pipeline decision with its own pilot rather than as part of a routine patch upgrade. Existing single-bundle projects are explicitly unaffected, so the safe default is to take the patch without touching webComponents.groups.

Compatibility. Declared backward compatible: PHP floor, Composer constraints, installation locations, single-bundle source discovery, output paths, and list JSON structure all unchanged. Note two practical caveats: grouped wc:list --json results add a group field, so any strict-schema parser of that output should be checked; and the empty-watch-session behaviour change can strand waiting scripts even though no API changed.

Sequencing.

1. Confirm PHP 8.4+ on target machines and runners — still the gate, still first.
2. Grep for wc:watch invocations in CI configs, package scripts, Composer scripts, and Makefiles; determine whether any depend on exit-on-empty.
3. Upgrade the global install, verify assegai --version, and confirm exit codes propagate for a deliberately failing command.
4. For the CLI-isolation fix, deliberately run with an older project-local Console present in a workspace and confirm the executing installation's classes remain authoritative.
5. Separately, pilot groups on one non-critical application: one group first, real esbuild, --group selection, wc:list --json shape, CSS-only change handling, and reload markers.
6. Only then test the multi-group path and the deletion behaviour (remove the last emitter of a stylesheet, rebuild, confirm what disappears and what breaks).
7. Roll out the CLI broadly; roll out groups per application after the pilot.

Operational Impact

Maintenance. Low for the CLI, moderate and real for groups. Groups add a configuration file to maintain, per-group caches to clean, lock files, and artifact ownership questions in public/. The prior maintenance concern — version drift between global and project-local installs — is partially mitigated by the CLI isolation fix, since an older project-local copy can no longer hijack extension discovery. Binary shadowing remains a documentation item, not a code fix.

Support. Expect two distinct ticket tails. Immediately post-rollout: "it says Unknown" and "the version looks wrong" from the 0.10.5 changes, plus a new "watch never exits" from empty sessions staying active. If groups are adopted: group configuration errors (unknown group, overlapping sources, path escaping workspace, cross-group import rejected), and "my stylesheet disappeared." All of these are designed behaviour and belong in the runbook so first-line response is verification, not escalation.

Scaling. The CLI still scales trivially — per-developer, no shared state. Groups change the scaling story: build cost now scales with group count and dependency-graph size, and parallel builds are safe across different groups but serialized within a group via locks. In CI with shared or cached workspaces, stale locks and .cache reuse are the scaling hazard, not load. Fleet consistency of install mode remains the other scaling concern.

Failure modes.

• Stale or orphaned locks — an interrupted build blocks the same group until cleared; different groups are unaffected.
• Orphaned watch children — teardown is coordinated on shutdown, but a hard kill can leave reload markers active or child processes alive.
• Hanging script — empty watch sessions no longer exit; scripted callers wait indefinitely.
• Silent artifact removal — a successful build that stops emitting a group stylesheet deletes the previously emitted one; pages referencing it break at deploy, not at build.
• Missing assets from misconfiguration — overlapping sources, no-glob source specs, or cross-group imports are rejected outright; a partial migration to groups will fail rather than degrade.
• Shadowed binary — documented, uncorrected; a user may believe they run 0.10.6 while executing an older copy.
• Platform gap — Windows untested, with a larger filesystem/process surface than before; Hostinger uncharacterized.
• Pre-1.0 churn — build configuration and emitted artifact contracts may change without a major-version signal.
• Version misreporting — fixed in 0.10.5; degrades to Unknown where metadata is genuinely absent.

Ramp-up. Under an hour for the CLI upgrade for a developer already on PHP 8.4, with one documentation page covering install mode, update command, version commands, exit-code behaviour, and the alias/PATH caveat. Groups are a materially larger ramp: the group model (no globs, no overlap, no cross-group component imports), the cache layout, and the artifact-ownership rule need a written internal convention before more than one team uses them. Budget a day for the first application, and treat the convention document as a prerequisite rather than a follow-up.

Recommendation. Adopt 0.10.6 as the baseline for existing Console usage — CLI isolation, exit-code forwarding, and the extension-discovery fix all strictly improve correctness with no compatibility cost. The one pre-rollout action is confirming nothing depends on wc:watch exiting on an empty source set. Decide on Web Component groups as a separate, later initiative: they are opt-in, they are functionally sound, and they are the first release where Console writes into application output paths — which warrants its own pilot on real esbuild, an explicit artifact-ownership rule, and a rollback story before broader commitment. Treat wider adoption as conditional on the PHP 8.4 floor and the absence of Windows requirements, both of which are unchanged and now carry more weight. Re-assess at the next minor or at 1.0, whichever comes first.