Healing Factor Laravel Package

Getting Started

• Install the package with Composer and publish its config/migrations: composer require <vendor>/healing-factor, then php artisan vendor:publish --tag=healing-factor-config and run migrations for the Issue Tracker Dashboard.
• Choose a driver in config/healing-factor.php:
  • CLI for local/dev — requires Claude Code or Opencode installed and authenticated on the machine.
  • API for environments without CLI tooling — set the Claude API key and budget limits.
• Ensure a queue worker is running. Healing happens in queued jobs, so without php artisan queue:work (or Horizon/Supervisor) nothing will be diagnosed or fixed.
• First use case: enable the exception listener in local or staging, trigger a common runtime error (undefined property, bad method call, query error), then inspect the queued job output and dashboard for the diagnosis and proposed fix. Review before applying anything.
• Look first at: config/healing-factor.php, the registered exception listener, the dashboard route, and the driver classes under vendor/<vendor>/healing-factor/src.

Implementation Patterns

• Local debugging loop: keep the listener enabled in dev, reproduce errors, let the queue generate a diagnosis/fix, then review the suggested diff and run tests before committing. Treat output as a senior pair-programmer suggestion, not an auto-merge.
• Staging triage: wire Bugsnag or Laravel Nightwatch webhooks to the package endpoint so staging/production-like errors create healing jobs automatically. Use the dashboard to prioritise recurring issues.
• Driver per environment: use CLI locally to avoid per-call API costs, and API in CI/staging/production where Claude Code/Opencode is unavailable. Disable entirely in environments where AI code changes are not allowed.
• Dedicated queue: route healing jobs to a separate queue (e.g. healing) with its own worker, retries, and backoff. This prevents slow AI calls from blocking normal application jobs.
• Webhook integration: secure inbound webhooks with a shared secret/signature, map payloads to the package’s exception listener, and rate-limit to avoid queue flooding from repeated errors.
• Review workflow: if the package can apply fixes automatically, restrict that to feature branches. Require tests and human approval before merging. Never auto-apply to production main.
• Dashboard usage: filter by environment, status, and exception class; link issues to logs and generated patches. Use it as a triage board rather than a replacement for Sentry/Bugsnag.
• Noise filtering: configure ignored exceptions (404s, validation errors, auth 401/403) so the queue and AI budget are spent on real bugs.
• Extension: if the package exposes driver/listener contracts, bind custom implementations for redaction, custom LLM providers, or ticket creation in your issue tracker.

Gotchas and Tips

• Boot-time errors are out of scope. Parse errors, fatal errors, and anything that prevents Laravel from booting or the queue from running cannot be healed. Keep conventional error monitoring for those.
• Queue reliability is critical. If the worker is down, healing silently stops. Monitor failed jobs, alert on failed_jobs, and supervise workers with Horizon or Supervisor.
• AI cost and rate limits. The API driver is pay-per-call. Set budgets, deduplicate repeated exceptions, and limit healing attempts per exception fingerprint. The CLI driver depends on local tool availability and auth, which often differs in production containers.
• Sensitive data leakage. Exceptions can contain PII, SQL, tokens, and request payloads. Review what is sent to Claude/API, enable redaction if supported, and restrict dashboard access.
• AI fixes need review. Generated patches can be plausible but wrong. Always run the test suite, inspect diffs, and use version control. Avoid automatic application in production without human approval.
• Environment parity. CLI driver may not exist in production. Either use the API driver there or disable the package in prod and rely on webhook-triggered healing in staging.
• Webhook security. Validate signatures/secrets, use HTTPS, and rate-limit inbound webhook endpoints. Do not expose an unauthenticated healing endpoint.
• Debugging pipeline issues. Start with a synthetic exception. Check storage/logs/laravel.log, the failed_jobs table, and driver-specific logs. Confirm the listener is registered and the queue connection matches your worker.
• Version pinning. v1.0 is new and AI behaviour can vary between runs. Pin the exact version and test upgrades in staging before rolling out.
• Extension points. Publish the config to customise exception classes, queue name, driver, redaction rules, and dashboard middleware. If contracts exist, bind custom drivers for your own LLM gateway or issue tracker.