Diagnostics

Diagnostics

Diagnostics adds operational diagnostics for cache, configuration drift, migrations, packages, registries, queues, permissions, setup health, and Tailwind build status.

At A Glance

• Package: capell-app/diagnostics
• Namespace: Capell\Diagnostics\
• Surfaces: Filament admin, console, database
• Service providers: packages/diagnostics/src/Providers/AdminServiceProvider.php, packages/diagnostics/src/Providers/DiagnosticsServiceProvider.php
• Capell dependencies: capell-app/admin, capell-app/core, capell-app/html-cache
• Third-party dependencies: croustibat/filament-jobs-monitor, lorisleiva/laravel-actions, spatie/laravel-data

Why It Helps Your Capell Workflow

• Gives developers and operators one admin surface for checking cache, config drift, migrations, packages, queues, permissions, setup health, and Tailwind status.
• Shortens support loops because package health checks can be found from Capell instead of by reading logs first.
• Reports whether declared package health checks are implemented, contract-only stubs, or broken declarations.
• Provides extension points for command-palette style diagnostic actions with explicit ability and risk metadata.

Best Used With

• Dashboard Reports
• Login Audit
• Deployments

What It Adds

Diagnostics adds operational diagnostics for cache, configuration drift, migrations, packages, registries, queues, permissions, setup health, and Tailwind build status.

• Command palette admin page.
• System health admin pages.
• Developer tools dashboard page.
• Permission audit report.
• Queue Operations report backed by croustibat/filament-jobs-monitor telemetry.
• Health widgets for cache, content, migrations, registry, setup, packages, and Tailwind.
• Secure command palette discovery, execution, feedback, and audit logging for developer tools, system health, queue health, and trusted capell:* Artisan operations.
• capell:diagnostics:health for running declared extension health checks from the console.

Why It Matters

For developers: Keeps diagnostics in actions and data objects so admin pages can show health information without hard-coded checks in the UI.

For teams: Helps operators and agencies see setup problems before they become publishing or deployment issues.

Built With

This package makes its Composer dependencies visible because they are part of the value proposition, not just plumbing. When an upstream package has a public repository, its linked preview card points readers back to the maintainers so their work gets proper credit.

Capell packages used here

• Capell Admin
• Capell Core

Open-source packages used here

• Laravel Actions - single-purpose action classes that keep package workflows out of controllers and Filament resources.
• Filament Jobs Monitor by Croustibat / Ultraviolettes - Laravel queue-event telemetry for the queue_monitors history that Capell wraps as Queue Operations.
• Spatie Laravel Data - typed data objects for package boundaries, form state, settings, and structured results.

Linked package previews

Screens And Workflow

Screenshots are generated from docs/screenshots.json during package deployment.

• Developer tools dashboard.
• Command palette page.
• System health page.
• Permission audit page.
• Queue Operations page with seeded queue-monitor history, failed jobs, and pending jobs.
• Health widgets on the admin dashboard.

Current runner screenshots are committed under packages/diagnostics/docs/screenshots. The capture contract now points at the Capell admin pages directly; keep operational data synthetic so Marketplace media never exposes real job names, customer payloads, or exception details.

Technical Shape

• DiagnosticsServiceProvider and AdminServiceProvider register admin pages and widgets.
• DiagnosticsServiceProvider configures croustibat/filament-jobs-monitor as the telemetry dependency, disables its upstream navigation, and routes queue UX through Capell Diagnostics.
• AdminServiceProvider registers palette command providers through the capell.diagnostics.command-palette-provider container tag.
• Command palette actions discover providers dynamically, authorize commands, validate parameters, execute navigation or Artisan commands, and record audit runs.
• Command palette output is redacted before it is returned or persisted to the audit table.
• RunExtensionHealthChecksAction resolves manifest-declared health checks, classifies implemented/stub/broken declarations, and executes runnable checks.
• Actions build each health report.
• Data objects describe report rows and dashboard state.
• QueueMonitor, FailedJob, and PendingQueueJob models support Queue Operations reporting.
• CommandPaletteRun model records command palette execution history.

Code Map

Admin Surface

• Pages: CommandPalettePage, DiagnosticsPage, PermissionAuditPage, PermissionAuditTable, QueueHealthPage, QueueHealthTable, SystemHealthPage.
• Widgets: AlertsWidgetAbstract, CacheHealthWidgetAbstract, ConfigDriftWidgetAbstract, ContentGraphHealthWidgetAbstract, ContentHealthWidgetAbstract, MigrationsHealthWidgetAbstract, PackagesInstalledWidgetAbstract, RegistryHealthWidgetAbstract, SetupHealthWidgetAbstract, SiteHealthWidgetAbstract, TailwindBuildStatusWidgetAbstract.

Data And Persistence

• This package owns the command_palette_runs table for command palette audit history.

• This package ships a guarded queue_monitors migration compatible with croustibat/filament-jobs-monitor so Capell installs do not depend on manual vendor publishing.

• It reads existing Laravel and Capell state such as config, migrations, failed jobs, permissions, packages, registries, and Tailwind outputs.

• Models: CommandPaletteRun, FailedJob, PendingQueueJob, QueueMonitor.

• Migrations: 2026_05_10_190846_01_create_command_palette_runs_table.php, 2026_05_29_000001_create_queue_monitors_table.php.

• Data objects live in src/Data/; use them for payloads, form state, and view models.

Extension Points

• Contracts: CommandPaletteProvider.
• Console: capell:diagnostics:health runs the extension health-check rollup with optional JSON output.
• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install Impact

• Adds admin pages for developer diagnostics.
• Adds dashboard widgets.
• Adds the command_palette_runs audit table.
• Adds the queue_monitors table when the host app has not already installed the upstream croustibat/filament-jobs-monitor table.
• No public routes are registered by this package.

Install And Setup

• Install with composer require capell-app/diagnostics in the host Capell application.
• Run migrations through the host application package install flow.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Admin And Access

• DiagnosticsPage (packages/diagnostics/src/Filament/Pages/DiagnosticsPage.php, slug diagnostics)

• CommandPalettePage (packages/diagnostics/src/Filament/Pages/CommandPalettePage.php, slug diagnostics/command-palette)

• PermissionAuditPage (packages/diagnostics/src/Filament/Pages/PermissionAuditPage.php, slug reports/permission-audit)

• QueueHealthPage / Queue Operations (packages/diagnostics/src/Filament/Pages/QueueHealthPage.php, slug reports/queue-health)

• SystemHealthPage (packages/diagnostics/src/Filament/Pages/SystemHealthPage.php, slug system-health)

• Gate: CacheHealthWidgetAbstract: admin, super_admin

• Gate: ConfigDriftWidgetAbstract: super_admin

• Gate: ContentHealthWidgetAbstract: editor, admin, super_admin

• Gate: DiagnosticsPage: Gate accessDiagnostics, viewDiagnostics

• Gate: MigrationsHealthWidgetAbstract: super_admin

• Gate: PackagesInstalledWidgetAbstract: super_admin

• Gate: QueueHealthPage: Gate accessDiagnostics, viewDiagnostics

• Gate: RegistryHealthWidgetAbstract: super_admin

• Gate: SetupHealthWidgetAbstract: settings-gated only

• Gate: SiteHealthWidgetAbstract: settings-gated only

• Gate: TailwindBuildStatusWidgetAbstract: super_admin

Common Pitfalls

• Some checks depend on host-app conventions and may need configuration.
• Queue Operations depends on croustibat/filament-jobs-monitor queue telemetry for history, Laravel failed job data for retries, and the database queue driver for pending-job rows.
• Permission audit output is only useful when permissions are registered.

Docs

• docs index
• command-palette.md
• credits-and-acknowledgements.md
• overview.md
• queue-operations.md

Testing

Run package tests from the repository root:

vendor/bin/pest packages/diagnostics/tests --configuration=phpunit.xml

Maintenance Notes

• Put behaviour changes in src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic.
• Use package Data classes at boundaries instead of passing anonymous arrays between layers.
• Use backed enums for persisted values and enum labels for Filament options.

Diagnostics

Status: Available, audited schema · Kind: package · Tier: premium · Bundle: operations · Contexts: admin, console · Product group: Capell Operations

This page is the consolidated implementation overview for the Diagnostics package. It is extracted from the package README, service providers, migrations, config files, routes, resources, models, actions, and the shared Capell ERD notes where available.

What This Package Adds

Diagnostics adds operational diagnostics for cache, configuration drift, migrations, packages, registries, queues, permissions, setup health, and Tailwind build status.

• Command palette admin page.
• System health admin pages.
• Developer tools dashboard page.
• Permission audit report.
• Queue Operations report backed by croustibat/filament-jobs-monitor queue telemetry.
• Health widgets for cache, content, migrations, registry, setup, packages, and Tailwind.
• Secure command palette discovery, execution, feedback, and audit logging for developer tools, system health, queue health, and trusted capell:* Artisan operations.
• Health-check reflection that reports implemented, stub, and broken manifest declarations across installed packages.
• capell:diagnostics:health for running declared extension health checks from the console.
• Health-check exports include an overall status, 0-100 score, worst severity, and per-check implementation/pass-fail rows.

Developer Notes

Keeps diagnostics in actions and data objects so admin pages can show health information without hard-coded checks in the UI.

• DiagnosticsServiceProvider and AdminServiceProvider register admin pages and widgets.
• AdminServiceProvider registers CapellArtisanPaletteCommandProvider and DiagnosticsPaletteCommandProvider through the capell.diagnostics.command-palette-provider tag.
• Command palette actions discover providers dynamically, authorize commands, validate parameters, execute navigation or Artisan commands, and record audit runs.
• Command palette output is redacted before response and audit persistence.
• RunExtensionHealthChecksAction resolves declared package health checks, classifies implementation status, and executes runnable checks.
• Actions build each health report.
• Data objects describe report rows and dashboard state.
• QueueMonitor, FailedJob, and PendingQueueJob models support Queue Operations reporting.
• Infrastructure status reports cover cache, queue, mail, and storage configuration.
• CommandPaletteRun model records command palette execution history.

Queue Operations

Diagnostics uses croustibat/filament-jobs-monitor, maintained at ultraviolettes/filament-jobs-monitor, as its low-level queue monitor. The upstream package listens to Laravel queue events and writes queue_monitors rows; Capell owns the Diagnostics page, permissions, Capell queue discovery, retry/delete Actions, retention config, and screenshot fixtures.

• Upstream navigation is disabled so operators use the Capell-native Queue Operations page.
• queue_monitors is created by a guarded Diagnostics migration when the upstream table is not already installed.
• Queue names are discovered from capell-diagnostics.queue_monitor.queues, package queue config paths, and the active Laravel queue connection.
• Pending database queue jobs are shown only when the database queue driver and jobs table are active.
• Retry, bulk retry, pending deletion, and pruning are handled by Diagnostics Actions.

See queue-operations.md for the focused runbook and upstream credit requirements.

Operational Notes

Helps operators and agencies see setup problems before they become publishing or deployment issues.

• Adds admin pages for developer diagnostics.
• Adds dashboard widgets.
• Adds the command_palette_runs audit table.
• No public routes are registered by this package.

Data And Retention

• This package owns the command_palette_runs table for command palette audit history.
• This package ships a guarded, upstream-compatible queue_monitors migration for croustibat/filament-jobs-monitor telemetry.
• It reads existing Laravel and Capell state such as config, migrations, failed jobs, permissions, packages, registries, and Tailwind outputs.

Screenshot Plan

• Developer tools dashboard.
• Health widgets on the admin dashboard.
• Queue Operations page with dummy queue_monitors, failed-job, and pending-job data.

Pitfalls

• Some checks depend on host-app conventions and may need configuration.
• Queue health needs access to failed job data.
• Permission audit output is only useful when permissions are registered.

Verification

• Run vendor/bin/pest packages/diagnostics/tests when package tests exist.
• Run the relevant host-app migration or package install flow in a disposable database.
• Open the listed admin or frontend surface and compare it with the screenshot plan.

Package Manifest

• Composer name: capell-app/diagnostics
• Product group: Capell Operations
• Kind: package
• Tier: premium
• Bundle: operations
• Contexts: admin, console
• Requires: capell-app/core, capell-app/admin
• Optional dependencies: None listed.
• Queue telemetry dependency: croustibat/filament-jobs-monitor.

Admin Surfaces

• DiagnosticsPage (packages/diagnostics/src/Filament/Pages/DiagnosticsPage.php, slug diagnostics)
• CommandPalettePage (packages/diagnostics/src/Filament/Pages/CommandPalettePage.php, slug diagnostics/command-palette)
• PermissionAuditPage (packages/diagnostics/src/Filament/Pages/PermissionAuditPage.php, slug reports/permission-audit)
• QueueHealthPage / Queue Operations (packages/diagnostics/src/Filament/Pages/QueueHealthPage.php, slug reports/queue-health)
• SystemHealthPage (packages/diagnostics/src/Filament/Pages/SystemHealthPage.php, slug system-health)

Commands

• Dynamic command palette metadata for trusted capell:* Artisan commands.
• Dynamic discovery happens through the capell.diagnostics.command-palette-provider provider tag.
• Commands can be navigation or Artisan commands and can define abilities, confirmation level, and parameters.
• Explicitly mapped low-risk commands can run without confirmation.
• Unknown dynamic capell:* commands require confirmation by default.
• Install, setup, and upgrade commands are marked dangerous when mapped.
• capell:diagnostics:health: runs declared extension health checks and supports --json or --csv exports.

Command Palette

• diagnostics.open: opens DiagnosticsPage.
• diagnostics.system-health: opens SystemHealthPage.
• diagnostics.queue-health: opens QueueHealthPage.
• artisan.capell:*: generated from available Capell Artisan commands, including command parameters.

Diagnostics owns the command palette UI, server-side authorization, validation, execution, notifications, and audit log records. Custom packages can add commands by implementing the package command provider contract and tagging the provider with capell.diagnostics.command-palette-provider.

Routes And Config

• None proven in this package directory.

Permissions And Gates

• Gate: CacheHealthWidgetAbstract: admin, super_admin
• Gate: ConfigDriftWidgetAbstract: super_admin
• Gate: ContentHealthWidgetAbstract: editor, admin, super_admin
• Gate: DiagnosticsPage: Gate accessDiagnostics, viewDiagnostics
• Gate: MigrationsHealthWidgetAbstract: super_admin
• Gate: PackagesInstalledWidgetAbstract: super_admin
• Gate: QueueHealthPage: Gate accessDiagnostics, viewDiagnostics
• Gate: RegistryHealthWidgetAbstract: super_admin
• Gate: SetupHealthWidgetAbstract: settings-gated only
• Gate: SiteHealthWidgetAbstract: settings-gated only
• Gate: TailwindBuildStatusWidgetAbstract: super_admin

Migrations

• create_command_palette_runs_table: stores command id, label, type, user, parameters, status, output, exit code, and executed timestamps.
• create_queue_monitors_table: guarded upstream-compatible table for croustibat/filament-jobs-monitor queue telemetry.

ERD Excerpt

command_palette_runs belongs to an optional user record and records each command palette execution for audit and debugging.

queue_monitors records queue job id, name, queue, attempt, progress, start/finish timestamps, failed state, exception summary, and optional tenant id. Rows are written by croustibat/filament-jobs-monitor and read by Capell Diagnostics.

Screenshot Automation

Deployment should read screenshots.json, install the package with demo data, resolve each admin surface or frontend URL, and write images to packages/diagnostics/docs/screenshots.

• Developer tools dashboard.
• Command palette page.
• System health page.
• Permission audit page.
• Queue health page.
• Health widgets on the admin dashboard.

The committed runner screenshots live under packages/diagnostics/docs/screenshots. Keep operational data synthetic so Marketplace media never exposes real job names, customer payloads, or exception details.