Nova Detached Actions Laravel Package

Technical Evaluation

Architecture fit. datomatic/nova-detached-actions is a narrow, additive Laravel Nova extension that lets an operator run an action from the index toolbar without first selecting rows. It introduces no migrations, no schema changes, no background services, and no domain-model footprint; it reuses Nova's native action pipeline (field definitions, confirmation modals, authorizedToRun(), response handling, shouldQueue). Blast radius is confined to the Nova admin surface and cannot affect public routes or APIs unless the wrapped action itself does. That makes it the right shape for genuinely resource-independent operations — imports, full-dataset exports, sync triggers, cache rebuilds, report generation, maintenance commands — and the wrong shape for anything semantically tied to a row selection, which should stay a standard Nova action. For a TPM, the important architectural point is that adoption is a convention decision (how we surface whole-dataset operations in admin) rather than an infrastructure commitment.

Integration feasibility. The install path is small: composer require, register the tool in NovaServiceProvider, define action classes, attach them to the resource index toolbar. A Nova-fluent developer can spike a working action in roughly half a day, and rollback is composer remove plus deletion of the action classes. The real feasibility gate is Nova version compatibility, not code complexity: Nova is closed-source and version-locked, so the package's laravel/nova constraint against our pin is the first thing to verify. With 11 stars and zero dependents, feasibility must be proven locally rather than inferred from ecosystem adoption.

Technical risk.

• Adoption risk (high): effectively zero ecosystem validation; no downstream projects will surface breakage before we do, and no community patches will materialize.
• Maintainer risk (high): single maintainer, no SLA. The April 2025 v3.0.0 release for Nova 5 is positive evidence of activity but not durability.
• Internal-coupling risk (medium-high): toolbar placement typically touches Nova's frontend/Vue or undocumented placement behaviour, making Nova major upgrades the most likely breakage vector. The failure mode is silent non-rendering, not an exception.
• Redundancy risk (medium): Nova has been improving native standalone/toolbar actions; confirm the gap still exists on our pinned version before accepting the dependency.
• Semantic risk (medium): detached actions run without selection context. Actions written against $models expecting selected resources will fail or, worse, silently operate on an unintended implicit scope. This is a code-review discipline problem, not a package bug.
• Authorization risk (medium, high tail severity): a toolbar button that bypasses authorizedToRun()/policy checks is a privilege-escalation surface and must be tested explicitly per action.
• Licensing risk (low): MIT — forkable and vendorable, which materially de-risks the maintainer exposure.

Key questions.

1. Which Nova major/minor versions are supported, and does the constraint cover our pinned Nova?
2. Does the package touch Nova's compiled frontend assets or private JS internals, and what is the per-Nova-release upgrade story?
3. Do authorization callbacks, confirmation modals, custom fields, and queued (shouldQueue) execution behave identically to standard Nova actions?
4. Are detached runs captured in ActionEvent history, preserving audit and incident forensics?
5. What is the test coverage and CI matrix across Nova/Laravel versions?
6. Has the maintainer signalled willingness to accept PRs, or is a fork the realistic long-term path?
7. Can we express the same outcome with native Nova standalone actions and avoid the dependency entirely?

Integration Approach

Stack fit. Laravel + Nova monolith or modular monolith, already committed to Nova as the admin surface — the package has no value outside that boundary, and Nova is a paid product, so this is additive cost only for teams already paying. It has no interaction with queue drivers, storage, or auth beyond what the wrapped actions already use; it is a presentation and registration layer. In multi-tenant Nova installs it is workable but requires explicit tenant scoping, because there is no selection context to imply scope.

Migration path. From a custom Vue toolbar component, a hacked toolbar partial, or a "select all, then act" workaround, this is a strict simplification: delete bespoke frontend code in favour of a class-based action. From a standard Nova action operators currently trigger after select-all, migration is a UX change plus a handle() signature rewrite — audit each action for $models assumptions before porting. Keep it reversible: run detached actions alongside their predecessors for one release cycle, then retire the old entry points. Rollback is removal of the tool registration plus the action classes.

Compatibility. Pin the package version explicitly and treat Nova upgrades as a coupled change: Nova bump → package constraint check → toolbar regression pass. Evaluate PHP, Laravel, and laravel/nova constraints together, since Nova's own constraint strategy frequently forces Laravel minor upgrades. Validate in a staging Nova instance with production-like policies, because authorization behaviour is the hardest thing to verify statically.

Sequencing.

1. Spike (1–2 days): install on a scratch branch, register one throwaway detached action, confirm rendering, confirmation modal, authorization, and queueing.
2. Version gate: confirm the supported Nova range matches our pin and record the supported matrix in the repo.
3. Pilot action: ship one low-risk, idempotent action (cache clear, read-only export, sync trigger) behind an admin-only policy.
4. Audit pattern: publish a review checklist — no implicit selection, explicit tenant/scope resolution, authorization required, queued when long-running, idempotent where possible.
5. Broaden: migrate remaining candidates one at a time, each with its own rollback.
6. Exit plan: document the fork procedure (MIT permits vendoring) and the native-Nova migration path if upstream goes quiet.

Operational Impact

Maintenance. The code volume is small enough that forking and owning it is a realistic fallback. Budget roughly one day per Nova major upgrade for compatibility verification, more if private internals are touched. Assign a named owner — an unowned, single-maintainer, frontend-touching dependency is the classic "breaks silently on upgrade" category. Track upstream releases and issues, and treat six months of silence as a trigger for the fork decision rather than a scramble. Record the fork intent and divergence log in the dependency register.

Support. There is no vendor SLA. Support is GitHub issues plus our own team; treat the package as source-available code we adopted, not a product we bought. Escalation is internal: read the source, patch, vendor. Keep any fork in a private repo with a documented divergence log so a second engineer can pick it up.

Scaling. The package itself does not scale — it is a UI affordance. Scaling is entirely a property of the actions it hosts, and detached actions invite "run once over everything" operations. Enforce shouldQueue, chunking, and rate limiting; a synchronous full-table export or recalculate-all triggered from a toolbar button will block a PHP worker and, at modest data volume, exhaust request timeouts and memory. Because the toolbar makes these operations one click away, frequency of execution goes up too — model queue throughput and database load against the new invocation pattern, not the old select-all flow.

Failure modes.

• Silent disappearance: a Nova upgrade ships and the toolbar buttons simply stop rendering. No error, no alert. Mitigation: an automated smoke test asserting button presence after every Nova bump, and a release-checklist item.
• Unauthorized invocation: an action's authorizedToRun() is not wired or is misconfigured, exposing a destructive operation to a broader admin group. Mitigation: per-action policy test in CI, and a negative test asserting the button is absent for unauthorized users.
• Unintended whole-dataset scope: a ported action still assumes $models and either errors or defaults to operating on everything. Mitigation: mandatory code review against the audit checklist; forbid $models usage in detached action classes.
• Double-click duplicate execution: a toolbar button invites repeat clicks; non-idempotent mutating actions can double-apply. Mitigation: idempotency keys, confirmation modals, and queue deduplication on anything that writes.
• Worker starvation: a long-running synchronous action blocks the admin UI and consumes a web worker. Mitigation: shouldQueue required for anything over a few seconds, with user-facing completion notification.
• Dependency abandonment: upstream goes quiet and the fork drifts. Mitigation: documented six-month silence trigger and a reimplementation escape hatch, which is viable given the small surface area.

Ramp-up. Low for engineers already fluent in Nova — one spike and the audit checklist is enough for a mid-level developer to contribute a compliant action. The ramp-up cost is organizational, not technical: teams must internalize the convention that detached actions carry no implicit scope, that authorization is per-action and explicit, and that queued execution is the default for anything touching many rows. Plan a short internal write-up plus one reviewed reference action as the template. Broader stakeholder communication is straightforward — frame it to executives as a free, MIT-licensed convenience layer on an admin panel already paid for, with effectively zero direct cost, a named internal owner, and classification as tactical internal tooling rather than strategic infrastructure. Practical gate before approval: at least two qualifying resource-independent actions on the roadmap, a named owner, confirmed Nova version compatibility, and a pilot action that has demonstrably proven authorization, queueing, and audit behaviour.