Laravel Toolkit Laravel Package

Getting Started

• Install the package as a dev dependency and confirm the toolkit:* artisan commands are registered (php artisan list | grep toolkit). The daily driver is composer preflight; run it before every PR.
• In a fresh git worktree or a new ticket branch, run php artisan toolkit:tia check first. It tells you whether Pest's TIA cache for this path exists, so you know in one command why your first test run was slow.
• First use case: create a worktree off a branch that has already landed work, run toolkit:tia inherit, then run composer test. The suite should run a small impact set rather than everything.
• Read the "Running Tests" project guideline alongside this package — it explains why the preflight coverage gate must stay unfiltered, and it is the contract the new preflight check enforces.

Implementation Patterns

• Baseline lifecycle, two halves. On the branch you merge into, run php artisan toolkit:tia publish after the merge lands (ideally in the post-merge CI job) to hand on that branch's final, complete baseline. In any checkout cut from that branch, run php artisan toolkit:tia inherit to adopt it under the worktree's own path key. Do the publish from a full, clean run — never from a partial or filtered one.
• Any base branch works. publish/inherit are not hardcoded to main; wire them into release branches, develop, and stacked-branch flows the same way. This also fixes the common failure where main's own checkout sits on an unrelated branch and the copied cache records no commit.
• Delete your homegrown cache-copying. If composer.json scripts or CI steps cp/rsync Pest's TIA cache between checkouts, remove them. toolkit:tia tracks Pest's cache format, so those scripts become the thing that breaks on a Pest upgrade.
• Keep selection flags out of the gate. composer preflight must run the full suite so the coverage gate produces a baseline worth handing on. Use --exclude-testsuite=Browser and similar selection flags on composer test / direct Pest invocations during the inner loop, not on preflight.
• Local retries without noise. Use php artisan toolkit:retry --no-notify when re-running a failed job while iterating; drop the flag for CI-facing retries where the notification is the point.
• CI sketch: merge job → toolkit:tia publish; developer job → toolkit:tia check (fail fast / report) → toolkit:tia inherit → composer test. Treat a missing baseline as a warning, not a hard failure.

Gotchas and Tips

• toolkit:tia check is your debugger. If a worktree re-runs everything, check distinguishes "no baseline recorded" from "baseline inherited but stale". Most surprises come from publishing off a branch whose checkout was on a different branch at the time.
• Publishing an incomplete baseline is worse than none. A filtered run records a selection that omits tests, so downstream worktrees silently skip coverage. The new preflight refusal exists precisely because a selection flag "switches TIA off" — expect a hard error, not a warning, if you combine them.
• Guard hook: earlier versions blocked pest --baseline, which only prints the cache directory and runs no tests. If you pinned below v0.4.0, that command will fail in hooked repos — upgrade rather than adding bypasses.
• --no-notify exists on toolkit:retry in v0.4.0 but not in earlier releases; scripts passing it to an older version will error out, so bump the constraint alongside the script change.
• Worktrees are keyed by path. Renaming or moving a worktree invalidates its inherited baseline; re-run inherit after a move rather than assuming the cache followed.
• Extension points: the guard hook and the toolkit:* commands are the intended seams — vendor a hook or a composer script against them rather than reimplementing Pest cache handling, so the next Pest cache-format change lands as a package bump instead of an app-wide fix.