ADR-048: Diagnostics tools 

Context 

The tool family answers content, schema, configuration, code and file questions — but "establish the system context first" still needed a human: which extensions and versions run here, which sites exist, did the nightly task fire, is this a composer-mode v14 on PostgreSQL, what does the deprecation log say, which middleware could intercept this request. Every diagnosis conversation starts with a subset of these.

Decision 

Six read-only, admin-only built-in tools — they enumerate the instance's configuration and attack surface, so none is offered to non-admins:

list_extensions (group system)

Active packages with key, version, composer name and title via PackageManager. Package paths never egress.

get_site_config (group configuration)

Site listing, or one site's configuration flattened to dotted key: value lines. Keys matching the credential pattern of TableReadAccessService redact their value — with camelCase normalization (apiKey → api_Key) because site settings are commonly camelCase while the pattern is snake_case-segment based. Output is line- and value-capped, never raw YAML.

list_scheduler_tasks (group system)

Plain columns of tx_scheduler_task only. The serialized_task_object blob is never unserialized — feeding a DB-supplied object graph to unserialize() is an object-injection primitive, and the plain columns answer the diagnostic question. The column set differs between 13.4 (SQL-defined) and 14 (TCA-defined, adds tasktype), so available columns are introspected per instance. An absent table degrades to "Scheduler is not installed."

get_system_status (group system)

TYPO3/PHP/database versions, application context, composer mode, OS family, timezone — versions and flags only, no paths, no hostnames. The database version comes from Doctrine's Connection::getServerVersion() (dbal  4.4 on both 13.4 and 14).

list_deprecations (group system)

Tail of the newest var/log/typo3_deprecations_*.log: distinct messages deduplicated with a ×count suffix, absolute project paths rewritten to relative, width- and count-capped. A missing file or disabled channel degrades to a plain message.

list_middlewares (group system)

One PSR-15 stack in execution order via MiddlewareStackResolver — @internal core API (same caveat as the include-tree classes used by check_typoscript, ADR-046); its return type differs across versions (array on 13.4, ArrayObject on 14) and is consumed as an iterable. Resolution failures collapse into one neutral message.

Considered and rejected 

list_event_listeners was part of the original idea list: the core ListenerProvider exposes no stable public enumeration API across 13.4 and 14, so a listener inventory would depend on container internals that change per version. Dropped until the core offers a supported way.

Consequences 

• A model can establish the full system context (versions, extensions, sites, automation, upgrade debt, request pipeline) without a human relaying installer or reports-module screenshots.
• All six are admin-only; the system/configuration group toggles (ADR-043) disable them centrally, per configuration and per run.
• Two @internal core APIs are consumed (MiddlewareStackResolver here, the include-tree scanner in ADR-046) — accepted as the only practical access path, guarded by neutral failure modes and the CI matrix across both supported majors.