Checkpoint Laravel Package

Getting Started

Checkpoint is a pre-flight/readiness tool: one artisan entry point runs a battery of checks (environment, config, security, dependency CVEs) and tells you whether the app is safe to ship. In 1.2.1 it is no longer npm-only for the frontend audit — Bun projects are first-class.

1. Install as a dev dependency (it belongs in local + CI, not on the production runtime):

   composer require --dev andreapollastri/checkpoint
   

2. Publish the config with php artisan vendor:publish and select the Checkpoint entry. Everything that matters — which checks run, which are fatal, thresholds — lives in that file, so read it before running anything.
3. Discover the commands rather than guessing signatures (the namespace is checkpoint:*):

   php artisan list checkpoint
   

   You will see the main run command plus generators such as checkpoint:github.
4. Run it once locally and read the output end to end. You want to see which checks are active by default and which of them fail on your machine — a CVE audit, for example, needs network access and will be noisy on a laptop behind a proxy.
5. First real use case: php artisan checkpoint:github to emit a workflow stub into .github/workflows/, commit it, and let it gate pull requests. That is the highest-leverage five minutes you can spend with this package — it turns a manual "did I remember to check X?" ritual into a required status check.

If you use Bun, upgrade to 1.2.1 before generating that stub: the emitted workflow now installs Bun when a Bun lockfile is present, and the audit check runs bun audit instead of silently skipping your frontend dependencies.

Implementation Patterns

Local pre-deploy ritual. Wire the run command into a Composer script so it fires before you tag a release:

"scripts": {
    "preflight": ["@php artisan checkpoint:run"]
}

composer preflight becomes the muscle-memory command before git tag.

CI gate, generated then owned. Treat the checkpoint:github output as a starting point, not a managed artifact — the stub is written once and never rewritten on upgrade. Commit it, then edit it: pin action versions, add your PHP matrix, and add caching. Keeping the generated file under review is what lets you notice when a release like 1.2.1 changes what the stub would have produced.

Split profiles by environment. Expensive, network-dependent checks (CVE audits) should be enabled in CI and optionally disabled locally so day-to-day runs stay under a second. Cheap deterministic checks — debug mode off, app key set, .env not committed — should run everywhere. Configure this in the published config rather than by passing ad-hoc flags, so local and CI cannot drift.

Frontend layout for monorepos. The Bun detection in 1.2.1 is lockfile-driven: bun.lock/bun.lockb present with no package-lock.json alongside it. If your frontend lives in resources/js or a frontend/ subdirectory, verify the check resolves the lockfile where you actually keep it; if not, the audit quietly reports nothing to do. Run the command and confirm the audit check reports on your Bun dependencies rather than passing trivially.

Custom checks. If your version exposes a checker contract or a config-level callback list, register project-specific invariants there — a migration-pending check, a queue-worker config check, a "no dd( in app/" grep. Keeping them inside Checkpoint means one command and one CI signal instead of five ad-hoc scripts.

Ordering and fail-fast. Put cheap, high-signal checks first. In CI, a failing debug-mode check should abort before a two-minute composer audit + bun audit round trip.

Gotchas and Tips

• package-lock.json wins over Bun. Presence of package-lock.json forces the npm path even if bun.lock exists. If you migrated to Bun, delete the stale npm lockfile — otherwise you are auditing the wrong dependency tree and will not notice.
• "Warns if Bun cannot run" is a soft failure. On a runner without the Bun binary, the audit degrades to a warning rather than a red build. If your pipeline treats warnings as non-fatal, you get a green build with an unaudited frontend. Make sure Bun is actually installed in every environment where the check is enabled, and verify the first green CI run actually executed bun audit.
• bun audit needs a reasonably recent Bun. Older binaries do not have the subcommand and will land in the warning path described above. Pin the Bun version in the workflow instead of floating to latest.
• Regenerate the workflow stub deliberately. 1.2.1 changes what checkpoint:github emits; existing committed workflows are untouched. Diff a freshly generated stub against yours to pick up the Bun setup step, then port it manually so you do not lose your customisations.
• Both lockfile flavours are supported — bun.lockb (binary, pre-1.2 Bun) and bun.lock (text, 1.2+). The binary one will not diff usefully; make sure it is marked as binary in .gitattributes so reviews are not a wall of garbage.
• Audits are network calls. They hit the registry, can be rate-limited, and can flake. Add generous timeouts and consider running CVE checks on a schedule (nightly) in addition to the PR gate, so transient registry failures do not block unrelated pull requests.
• Exit codes are the contract. Before you make this a required check, confirm exactly which statuses fail the build. A check that only warns is a check nobody reads.
• config:cache in CI. If your pipeline caches config before the checkpoint step, config edits made in the same job will not take effect. Order matters.
• Pin it. As a dev dependency it is locked by composer.lock; upgrade deliberately and read the changelog — 1.2.1 is additive and safe, but audit-adjacent changes are exactly the ones you want to notice.
• Debugging a single failure: re-run with verbose output and inspect the config entry for that check rather than the command as a whole. Most surprises are a check that is enabled in one profile and not the other.