@wpmoo/toolkit 0.9.26 → 0.9.27

package/README.md

@@ -170,12 +170,31 @@ npx @wpmoo/toolkit doctor --json --postgres
 ```
 
 JSON output is optional; human-readable output remains the default.
-`doctor --postgres` adds read-only PostgreSQL health and performance diagnostics
-such as database size, sessions currently running queries with
-`pg_stat_activity.state = 'active'`, connection utilization against
-`max_connections`, slow-query readiness, extension visibility, and settings.
+`doctor --postgres` runs read-only PostgreSQL diagnostics as advisory checks only; it
+does not perform automatic tuning.
+Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics
+instead of being treated as successful checks.
+
+Current advisory checks include:
+
+- sessions currently running queries where `pg_stat_activity.state = 'active'`;
+- connection utilization against `max_connections`;
+- long transaction / idle-in-transaction warnings from `pg_stat_activity`;
+- table health visibility (for example table and index bloat signals, index scan
+  efficiency, and vacuum-related blockers);
+- optional unused index advisory output when index usage data is available;
+- WAL and capacity visibility including WAL activity and disk-level pressure context;
+- slow-query and query-plan readiness checks for common `log_min_duration_statement`
+  and `pg_stat_statements` prerequisites.
+
+`npx @wpmoo/toolkit doctor --postgres` and
+`npx @wpmoo/toolkit doctor --json --postgres` use the same checks, and the
+JSON variant exposes a versioned PostgreSQL diagnostics contract.
+
 `doctor --json --postgres` includes a structured `postgres` object for automation.
-Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
+`doctor --json --postgres` keeps the JSON contract stable by versioning the
+`postgres` payload; individual fields are optional so automation can safely handle
+environments where PostgreSQL does not expose a metric.
 
 ## Release Artifacts
 

package/dist/doctor.js

@@ -5,6 +5,7 @@ import { detectComposeLayout, readEnvFile, selectedComposeEnvironment } from './
 import { dailyActionScripts } from './daily-actions.js';
 import { defaultPostgresVersion } from './external-templates.js';
 import { defaultOdooVersion, markerPath, replaceSourceRepos } from './environment.js';
+import { POSTGRES_DIAGNOSTICS_CONTRACT_VERSION, POSTGRES_DIAGNOSTICS_QUERY, malformedPostgresDiagnosticKeys, missingPostgresDiagnosticKeys, parsePostgresDiagnostics, postgresPostgresWarnings, renderPostgresDiagnostics, structuredPostgresDiagnostics, unavailablePostgresDiagnosticsWarning, } from './postgres-diagnostics.js';
 import { listGitmoduleSources, readSourceManifest, sourceReposFromManifest, sourceManifestPath, syncManifestFromMetadataAndGitmodules, writeSourceManifest, } from './source-manifest.js';
 const realCommandRunner = async (command, args, options) => {
     const result = await execa(command, args, { cwd: options.cwd });
@@ -46,128 +47,6 @@ function isMetadataError(message) {
         message.startsWith('Invalid sourceRepos entry in .wpmoo/odoo.json'));
 }
 const incompatiblePostgres18MountTargets = ['/var/lib/postgresql/data', '/var/lib/postgresql/18/docker'];
-const postgresDiagnosticQuery = `
-WITH metrics(metric, value) AS (
-  SELECT 'database_count', count(*)::text
-    FROM pg_database
-    WHERE datistemplate = false
-  UNION ALL
-  SELECT 'active_connections', count(*)::text
-    FROM pg_stat_activity
-    WHERE datname IS NOT NULL
-      AND state = 'active'
-  UNION ALL
-  SELECT 'connection_count', count(*)::text
-    FROM pg_stat_activity
-    WHERE datname IS NOT NULL
-  UNION ALL
-  SELECT 'max_connections', COALESCE(
-    (SELECT setting FROM pg_settings WHERE name = 'max_connections'),
-    'unavailable'
-  )
-  UNION ALL
-  SELECT 'total_database_size_bytes', COALESCE(sum(pg_database_size(datname)), 0)::text
-    FROM pg_database
-    WHERE datistemplate = false
-  UNION ALL
-  SELECT 'largest_database_name', COALESCE(
-    (
-      SELECT datname
-      FROM pg_database
-      WHERE datistemplate = false
-      ORDER BY pg_database_size(datname) DESC, datname
-      LIMIT 1
-    ),
-    'unavailable'
-  )
-  UNION ALL
-  SELECT 'largest_database_size_bytes', COALESCE(
-    (
-      SELECT pg_database_size(datname)::text
-      FROM pg_database
-      WHERE datistemplate = false
-      ORDER BY pg_database_size(datname) DESC, datname
-      LIMIT 1
-    ),
-    '0'
-  )
-  UNION ALL
-  SELECT 'slow_query_logging', COALESCE(
-    (SELECT setting || unit FROM pg_settings WHERE name = 'log_min_duration_statement'),
-    'unavailable'
-  )
-  UNION ALL
-  SELECT 'pg_stat_statements',
-    CASE
-      WHEN EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements') THEN 'installed'
-      WHEN EXISTS (SELECT 1 FROM pg_available_extensions WHERE name = 'pg_stat_statements') THEN 'available'
-      ELSE 'unavailable'
-    END
-  UNION ALL
-  SELECT 'pg_stat_statements_available_version', COALESCE(
-    (SELECT default_version FROM pg_available_extensions WHERE name = 'pg_stat_statements'),
-    'unavailable'
-  )
-  UNION ALL
-  SELECT 'pg_stat_statements_installed_version', COALESCE(
-    (SELECT extversion FROM pg_extension WHERE extname = 'pg_stat_statements'),
-    ''
-  )
-  UNION ALL
-  SELECT 'shared_preload_libraries', COALESCE(
-    (SELECT setting FROM pg_settings WHERE name = 'shared_preload_libraries'),
-    'unavailable'
-  )
-  UNION ALL
-  SELECT 'shared_buffers', COALESCE(
-    (SELECT setting FROM pg_settings WHERE name = 'shared_buffers'),
-    'unavailable'
-  )
-)
-SELECT metric || '|' || value
-FROM metrics
-ORDER BY CASE metric
-  WHEN 'database_count' THEN 1
-  WHEN 'active_connections' THEN 2
-  WHEN 'connection_count' THEN 3
-  WHEN 'max_connections' THEN 4
-  WHEN 'total_database_size_bytes' THEN 5
-  WHEN 'largest_database_name' THEN 6
-  WHEN 'largest_database_size_bytes' THEN 7
-  WHEN 'slow_query_logging' THEN 8
-  WHEN 'pg_stat_statements' THEN 9
-  WHEN 'pg_stat_statements_available_version' THEN 10
-  WHEN 'pg_stat_statements_installed_version' THEN 11
-  WHEN 'shared_preload_libraries' THEN 12
-  WHEN 'shared_buffers' THEN 13
-  ELSE 99
-END;
-`.trim();
-const postgresDiagnosticKeys = [
-    'database_count',
-    'active_connections',
-    'connection_count',
-    'max_connections',
-    'total_database_size_bytes',
-    'largest_database_name',
-    'largest_database_size_bytes',
-    'slow_query_logging',
-    'pg_stat_statements',
-    'pg_stat_statements_available_version',
-    'pg_stat_statements_installed_version',
-    'shared_preload_libraries',
-    'shared_buffers',
-];
-const requiredPostgresDiagnosticKeys = [
-    'database_count',
-    'active_connections',
-    'connection_count',
-    'max_connections',
-    'total_database_size_bytes',
-    'slow_query_logging',
-    'pg_stat_statements',
-    'shared_buffers',
-];
 function parsePostgresMajorFromValue(value) {
     if (!value)
         return undefined;
@@ -178,139 +57,8 @@ function parsePostgresMajorFromValue(value) {
     const match = trimmed.match(/postgres:([0-9]{1,3})(?:[-._][A-Za-z0-9._-]+)?(?:@[\w:.-]+)?/i);
     return match?.[1];
 }
-function parsePostgresDiagnostics(output) {
-    const diagnostics = {};
-    const allowedKeys = new Set(postgresDiagnosticKeys);
-    for (const rawLine of output.split(/\r?\n/u)) {
-        const line = rawLine.trim();
-        if (!line)
-            continue;
-        const separatorIndex = line.indexOf('|');
-        if (separatorIndex === -1)
-            continue;
-        const key = line.slice(0, separatorIndex).trim();
-        const value = line.slice(separatorIndex + 1).trim();
-        if (allowedKeys.has(key) && value) {
-            diagnostics[key] = value;
-        }
-    }
-    return diagnostics;
-}
-function renderPostgresDiagnostics(diagnostics) {
-    const connectionUtilizationPct = postgresConnectionUtilizationPct(diagnostics);
-    const parts = postgresDiagnosticKeys.flatMap((key) => {
-        const value = diagnostics[key];
-        const rendered = value ? [`${key}=${value}`] : [];
-        if (key === 'max_connections' && connectionUtilizationPct !== undefined) {
-            rendered.push(`connection_utilization_pct=${connectionUtilizationPct}`);
-        }
-        return rendered;
-    });
-    return parts.length > 0 ? `OK PostgreSQL diagnostics ${parts.join(' ')}` : undefined;
-}
-function missingPostgresDiagnosticKeys(diagnostics) {
-    return requiredPostgresDiagnosticKeys.filter((key) => !diagnostics[key]);
-}
-function unavailablePostgresDiagnosticsWarning(diagnostics, missingKeys) {
-    return Object.keys(diagnostics).length === 0
-        ? 'no diagnostic rows returned'
-        : `incomplete diagnostic rows: missing ${missingKeys.join(', ')}`;
-}
-function integerDiagnostic(value) {
-    if (!value || !/^\d+$/u.test(value)) {
-        return undefined;
-    }
-    return Number.parseInt(value, 10);
-}
-function malformedPostgresDiagnosticKeys(diagnostics) {
-    const numericKeys = [
-        'database_count',
-        'active_connections',
-        'connection_count',
-        'max_connections',
-        'total_database_size_bytes',
-        'largest_database_size_bytes',
-    ];
-    return numericKeys.filter((key) => diagnostics[key] !== undefined && integerDiagnostic(diagnostics[key]) === undefined);
-}
-function postgresConnectionUtilizationPct(diagnostics) {
-    const connectionCount = integerDiagnostic(diagnostics.connection_count);
-    const maxConnections = integerDiagnostic(diagnostics.max_connections);
-    if (connectionCount === undefined || maxConnections === undefined || maxConnections <= 0) {
-        return undefined;
-    }
-    return Math.round((connectionCount / maxConnections) * 100);
-}
-function postgresConnectionUtilizationWarning(diagnostics) {
-    const connectionCount = integerDiagnostic(diagnostics.connection_count);
-    const maxConnections = integerDiagnostic(diagnostics.max_connections);
-    const utilizationPct = postgresConnectionUtilizationPct(diagnostics);
-    if (connectionCount === undefined ||
-        maxConnections === undefined ||
-        utilizationPct === undefined ||
-        utilizationPct < 80) {
-        return undefined;
-    }
-    return `PostgreSQL connection utilization is high: ${utilizationPct}% of max_connections used (${connectionCount}/${maxConnections}).`;
-}
-function postgresSlowQueryLoggingWarning(diagnostics) {
-    const slowQueryLogging = diagnostics.slow_query_logging?.trim();
-    if (!slowQueryLogging || (!/^-1\s*(?:ms)?$/iu.test(slowQueryLogging) && !/^off$/iu.test(slowQueryLogging))) {
-        return undefined;
-    }
-    return `PostgreSQL slow-query logging is disabled (log_min_duration_statement=${slowQueryLogging}). Enable it before performance triage.`;
-}
-function postgresExtensionVisibilityWarning(diagnostics) {
-    if (diagnostics.pg_stat_statements === 'available' &&
-        diagnostics.pg_stat_statements_available_version &&
-        !diagnostics.pg_stat_statements_installed_version) {
-        return 'PostgreSQL pg_stat_statements is available but not installed. Install it before query-level performance triage.';
-    }
-    return undefined;
-}
-function structuredPostgresDiagnostics(diagnostics) {
-    const structured = {};
-    const databaseCount = integerDiagnostic(diagnostics.database_count);
-    const activeConnections = integerDiagnostic(diagnostics.active_connections);
-    const connectionCount = integerDiagnostic(diagnostics.connection_count);
-    const maxConnections = integerDiagnostic(diagnostics.max_connections);
-    const connectionUtilizationPct = postgresConnectionUtilizationPct(diagnostics);
-    const totalDatabaseSizeBytes = integerDiagnostic(diagnostics.total_database_size_bytes);
-    const largestDatabaseSizeBytes = integerDiagnostic(diagnostics.largest_database_size_bytes);
-    if (databaseCount !== undefined)
-        structured.databaseCount = databaseCount;
-    if (activeConnections !== undefined)
-        structured.activeConnections = activeConnections;
-    if (connectionCount !== undefined)
-        structured.connectionCount = connectionCount;
-    if (maxConnections !== undefined)
-        structured.maxConnections = maxConnections;
-    if (connectionUtilizationPct !== undefined)
-        structured.connectionUtilizationPct = connectionUtilizationPct;
-    if (totalDatabaseSizeBytes !== undefined)
-        structured.totalDatabaseSizeBytes = totalDatabaseSizeBytes;
-    if (diagnostics.largest_database_name)
-        structured.largestDatabaseName = diagnostics.largest_database_name;
-    if (largestDatabaseSizeBytes !== undefined)
-        structured.largestDatabaseSizeBytes = largestDatabaseSizeBytes;
-    if (diagnostics.slow_query_logging)
-        structured.slowQueryLogging = diagnostics.slow_query_logging;
-    if (diagnostics.pg_stat_statements)
-        structured.pgStatStatements = diagnostics.pg_stat_statements;
-    if (diagnostics.pg_stat_statements_available_version) {
-        structured.pgStatStatementsAvailableVersion = diagnostics.pg_stat_statements_available_version;
-    }
-    if (diagnostics.pg_stat_statements_installed_version) {
-        structured.pgStatStatementsInstalledVersion = diagnostics.pg_stat_statements_installed_version;
-    }
-    if (diagnostics.shared_preload_libraries)
-        structured.sharedPreloadLibraries = diagnostics.shared_preload_libraries;
-    if (diagnostics.shared_buffers)
-        structured.sharedBuffers = diagnostics.shared_buffers;
-    return structured;
-}
 async function readPostgresDiagnostics(target, runner) {
-    const queryLiteral = JSON.stringify(postgresDiagnosticQuery);
+    const queryLiteral = JSON.stringify(POSTGRES_DIAGNOSTICS_QUERY);
     const command = [
         `query=${queryLiteral}`,
         '. ./scripts/lib.sh >/dev/null',
@@ -716,21 +464,11 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
                 }
                 report.postgres = {
                     requested: true,
+                    contractVersion: POSTGRES_DIAGNOSTICS_CONTRACT_VERSION,
                     available: true,
                     diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
                 };
-                const connectionUtilizationWarning = postgresConnectionUtilizationWarning(postgresDiagnostics);
-                if (connectionUtilizationWarning) {
-                    warnings.push(connectionUtilizationWarning);
-                }
-                const slowQueryLoggingWarning = postgresSlowQueryLoggingWarning(postgresDiagnostics);
-                if (slowQueryLoggingWarning) {
-                    warnings.push(slowQueryLoggingWarning);
-                }
-                const extensionVisibilityWarning = postgresExtensionVisibilityWarning(postgresDiagnostics);
-                if (extensionVisibilityWarning) {
-                    warnings.push(extensionVisibilityWarning);
-                }
+                warnings.push(...postgresPostgresWarnings(postgresDiagnostics));
             }
             else {
                 const warning = malformedKeys.length > 0
@@ -739,6 +477,7 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
                 warnings.push(`PostgreSQL diagnostics unavailable: ${warning}`);
                 report.postgres = {
                     requested: true,
+                    contractVersion: POSTGRES_DIAGNOSTICS_CONTRACT_VERSION,
                     available: false,
                     diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
                     warning,
@@ -750,6 +489,7 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
             warnings.push(`PostgreSQL diagnostics unavailable: ${warning}`);
             report.postgres = {
                 requested: true,
+                contractVersion: POSTGRES_DIAGNOSTICS_CONTRACT_VERSION,
                 available: false,
                 diagnostics: {},
                 warning,

package/dist/postgres-diagnostics.js

@@ -0,0 +1,646 @@
+export const POSTGRES_DIAGNOSTICS_CONTRACT_VERSION = 2;
+export const POSTGRES_DIAGNOSTICS_QUERY = `
+WITH
+transaction_health AS (
+  SELECT
+    COALESCE(
+      COUNT(*) FILTER (
+        WHERE state = 'active'
+          AND xact_start IS NOT NULL
+          AND now() - xact_start > interval '5 minutes'
+      ),
+      0
+    )::text AS long_transaction_count,
+    COALESCE(
+      MAX(
+        EXTRACT(EPOCH FROM now() - xact_start)
+      ) FILTER (
+        WHERE state = 'active'
+          AND xact_start IS NOT NULL
+          AND now() - xact_start > interval '5 minutes'
+      ),
+      0
+    )::bigint::text AS oldest_long_transaction_age_seconds,
+    COALESCE(
+      COUNT(*) FILTER (
+        WHERE state = 'idle in transaction'
+          AND xact_start IS NOT NULL
+          AND now() - xact_start > interval '5 minutes'
+      ),
+      0
+    )::text AS idle_in_transaction_count,
+    COALESCE(
+      MAX(
+        EXTRACT(EPOCH FROM now() - xact_start)
+      ) FILTER (
+        WHERE state = 'idle in transaction'
+          AND xact_start IS NOT NULL
+          AND now() - xact_start > interval '5 minutes'
+      ),
+      0
+    )::bigint::text AS oldest_idle_in_transaction_age_seconds
+  FROM pg_stat_activity
+  WHERE datname IS NOT NULL
+),
+table_health AS (
+  SELECT
+    COALESCE(
+      COUNT(*) FILTER (
+        WHERE n_live_tup > 0
+          AND n_dead_tup::numeric > 0
+          AND (n_dead_tup::numeric / NULLIF(n_live_tup::numeric, 0)) > 0.2
+      ),
+      0
+    )::text AS table_health_risky_table_count,
+    COALESCE(
+      COUNT(*) FILTER (
+        WHERE n_dead_tup::numeric > 0
+          AND (n_dead_tup::numeric / NULLIF(n_live_tup::numeric, 0)) > 0.2
+      ),
+      0
+    )::text AS table_health_requires_vacuum_count,
+    COALESCE(
+      COUNT(*) FILTER (WHERE n_mod_since_analyze > 1000),
+      0
+    )::text AS table_health_requires_analyze_count
+  FROM pg_stat_user_tables
+),
+table_health_ranked AS (
+  SELECT
+    schemaname,
+    relname,
+    CASE
+      WHEN n_live_tup > 0 THEN (n_dead_tup::numeric / NULLIF(n_live_tup::numeric, 0))
+      ELSE 0
+    END AS dead_tuple_ratio,
+    n_dead_tup AS dead_tup_count,
+    n_live_tup,
+    ROW_NUMBER() OVER (
+      ORDER BY
+        CASE WHEN n_live_tup > 0 THEN n_dead_tup::numeric / NULLIF(n_live_tup::numeric, 0) ELSE 0 END DESC,
+        n_dead_tup DESC,
+        n_live_tup DESC
+    ) AS rn
+  FROM pg_stat_user_tables
+),
+top_table_health AS (
+  SELECT
+    COALESCE(
+      (SELECT format('%I.%I', schemaname, relname) FROM table_health_ranked WHERE rn = 1),
+      'unavailable'
+    ) AS table_health_top_risky_table,
+    COALESCE(
+      (
+        SELECT dead_tuple_ratio
+        FROM table_health_ranked
+        WHERE rn = 1
+      )::text,
+      '0'
+    ) AS table_health_top_risky_dead_tuple_ratio,
+    COALESCE(
+      (
+        SELECT dead_tup_count
+        FROM table_health_ranked
+        WHERE rn = 1
+      )::text,
+      '0'
+    ) AS table_health_top_risky_dead_tuple_count
+  FROM (SELECT 1) AS _top_table_health_row
+),
+index_health AS (
+  SELECT
+    COALESCE(
+      COUNT(*) FILTER (
+        WHERE NOT idx.indisunique
+          AND i.idx_scan = 0
+          AND i.idx_tup_fetch = 0
+      ),
+      0
+    )::text AS unused_index_candidates_count
+  FROM pg_stat_user_indexes i
+  LEFT JOIN pg_index idx ON idx.indexrelid = i.indexrelid
+  WHERE i.schemaname NOT IN ('pg_catalog', 'information_schema')
+),
+wal_health AS (
+  SELECT
+    COALESCE((SELECT setting FROM pg_settings WHERE name = 'wal_level'), 'unavailable')::text AS wal_level,
+    COALESCE((SELECT setting FROM pg_settings WHERE name = 'archive_mode'), 'unavailable')::text AS wal_archive_mode,
+    COALESCE((SELECT COUNT(*) FROM pg_ls_waldir()), 0)::text AS wal_file_count,
+    COALESCE((SELECT SUM(size) FROM pg_ls_waldir()), 0)::text AS wal_directory_size_bytes
+),
+capacity_health AS (
+  SELECT
+    COALESCE((SELECT pg_tablespace_size('pg_default')), 0)::text AS default_tablespace_size_bytes,
+    COALESCE(
+      (SELECT SUM(n_tup_ins + n_tup_upd + n_tup_del) FROM pg_stat_database WHERE datname IS NOT NULL),
+      0
+    )::text AS database_write_activity_rows
+)
+SELECT metric || '|' || value
+FROM (
+  SELECT 'database_count'::text AS metric, count(*)::text AS value
+  FROM pg_database
+  WHERE datistemplate = false
+  UNION ALL
+  SELECT 'active_connections', COUNT(*)::text
+  FROM pg_stat_activity
+  WHERE datname IS NOT NULL
+    AND state = 'active'
+  UNION ALL
+  SELECT 'connection_count', COUNT(*)::text
+  FROM pg_stat_activity
+  WHERE datname IS NOT NULL
+  UNION ALL
+  SELECT 'max_connections', COALESCE(
+    (SELECT setting FROM pg_settings WHERE name = 'max_connections'),
+    'unavailable'
+  )::text
+  UNION ALL
+  SELECT 'total_database_size_bytes', COALESCE(SUM(pg_database_size(datname)), 0)::text
+  FROM pg_database
+  WHERE datistemplate = false
+  UNION ALL
+  SELECT 'largest_database_name', COALESCE(
+    (
+      SELECT datname
+      FROM pg_database
+      WHERE datistemplate = false
+      ORDER BY pg_database_size(datname) DESC, datname
+      LIMIT 1
+    ),
+    'unavailable'
+  )
+  UNION ALL
+  SELECT 'largest_database_size_bytes', COALESCE(
+    (
+      SELECT pg_database_size(datname)::text
+      FROM pg_database
+      WHERE datistemplate = false
+      ORDER BY pg_database_size(datname) DESC, datname
+      LIMIT 1
+    ),
+    '0'
+  )
+  UNION ALL
+  SELECT 'slow_query_logging', COALESCE(
+    (SELECT setting || COALESCE(unit, '') FROM pg_settings WHERE name = 'log_min_duration_statement'),
+    'unavailable'
+  )
+  UNION ALL
+  SELECT 'pg_stat_statements',
+    CASE
+      WHEN EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements') THEN 'installed'
+      WHEN EXISTS (SELECT 1 FROM pg_available_extensions WHERE name = 'pg_stat_statements') THEN 'available'
+      ELSE 'unavailable'
+    END
+  UNION ALL
+  SELECT 'pg_stat_statements_available_version', COALESCE(
+    (SELECT default_version FROM pg_available_extensions WHERE name = 'pg_stat_statements'),
+    'unavailable'
+  )
+  UNION ALL
+  SELECT 'pg_stat_statements_installed_version', COALESCE(
+    (SELECT extversion FROM pg_extension WHERE extname = 'pg_stat_statements'),
+    ''
+  )
+  UNION ALL
+  SELECT 'shared_preload_libraries', COALESCE(
+    (SELECT setting FROM pg_settings WHERE name = 'shared_preload_libraries'),
+    'unavailable'
+  )
+  UNION ALL
+  SELECT 'shared_buffers', COALESCE(
+    (SELECT setting FROM pg_settings WHERE name = 'shared_buffers'),
+    'unavailable'
+  )
+  UNION ALL
+  SELECT 'long_transaction_count', long_transaction_count FROM transaction_health
+  UNION ALL
+  SELECT 'oldest_long_transaction_age_seconds', oldest_long_transaction_age_seconds FROM transaction_health
+  UNION ALL
+  SELECT 'idle_in_transaction_count', idle_in_transaction_count FROM transaction_health
+  UNION ALL
+  SELECT 'oldest_idle_in_transaction_age_seconds', oldest_idle_in_transaction_age_seconds FROM transaction_health
+  UNION ALL
+  SELECT 'table_health_risky_table_count', table_health_risky_table_count FROM table_health
+  UNION ALL
+  SELECT 'table_health_requires_vacuum_count', table_health_requires_vacuum_count FROM table_health
+  UNION ALL
+  SELECT 'table_health_requires_analyze_count', table_health_requires_analyze_count FROM table_health
+  UNION ALL
+  SELECT 'table_health_top_risky_table', table_health_top_risky_table FROM top_table_health
+  UNION ALL
+  SELECT 'table_health_top_risky_dead_tuple_ratio', table_health_top_risky_dead_tuple_ratio FROM top_table_health
+  UNION ALL
+  SELECT 'table_health_top_risky_dead_tuple_count', table_health_top_risky_dead_tuple_count FROM top_table_health
+  UNION ALL
+  SELECT 'unused_index_candidates_count', unused_index_candidates_count FROM index_health
+  UNION ALL
+  SELECT 'wal_level', wal_level FROM wal_health
+  UNION ALL
+  SELECT 'wal_archive_mode', wal_archive_mode FROM wal_health
+  UNION ALL
+  SELECT 'wal_file_count', wal_file_count FROM wal_health
+  UNION ALL
+  SELECT 'wal_directory_size_bytes', wal_directory_size_bytes FROM wal_health
+  UNION ALL
+  SELECT 'default_tablespace_size_bytes', default_tablespace_size_bytes FROM capacity_health
+  UNION ALL
+  SELECT 'database_write_activity_rows', database_write_activity_rows FROM capacity_health
+) metrics
+ORDER BY metric;
+`.trim();
+export const POSTGRES_DIAGNOSTIC_KEYS = [
+    'database_count',
+    'active_connections',
+    'connection_count',
+    'max_connections',
+    'total_database_size_bytes',
+    'largest_database_name',
+    'largest_database_size_bytes',
+    'slow_query_logging',
+    'pg_stat_statements',
+    'pg_stat_statements_available_version',
+    'pg_stat_statements_installed_version',
+    'shared_preload_libraries',
+    'shared_buffers',
+    'long_transaction_count',
+    'oldest_long_transaction_age_seconds',
+    'idle_in_transaction_count',
+    'oldest_idle_in_transaction_age_seconds',
+    'table_health_risky_table_count',
+    'table_health_requires_vacuum_count',
+    'table_health_requires_analyze_count',
+    'table_health_top_risky_table',
+    'table_health_top_risky_dead_tuple_ratio',
+    'table_health_top_risky_dead_tuple_count',
+    'unused_index_candidates_count',
+    'wal_level',
+    'wal_archive_mode',
+    'wal_file_count',
+    'wal_directory_size_bytes',
+    'default_tablespace_size_bytes',
+    'database_write_activity_rows',
+];
+export const REQUIRED_POSTGRES_DIAGNOSTIC_KEYS = [
+    'database_count',
+    'active_connections',
+    'connection_count',
+    'max_connections',
+    'total_database_size_bytes',
+    'slow_query_logging',
+    'pg_stat_statements',
+    'shared_buffers',
+];
+const INTEGER_POSTGRES_DIAGNOSTIC_KEYS = [
+    'database_count',
+    'active_connections',
+    'connection_count',
+    'max_connections',
+    'total_database_size_bytes',
+    'largest_database_size_bytes',
+    'long_transaction_count',
+    'oldest_long_transaction_age_seconds',
+    'idle_in_transaction_count',
+    'oldest_idle_in_transaction_age_seconds',
+    'table_health_risky_table_count',
+    'table_health_requires_vacuum_count',
+    'table_health_requires_analyze_count',
+    'table_health_top_risky_dead_tuple_count',
+    'unused_index_candidates_count',
+    'wal_file_count',
+    'wal_directory_size_bytes',
+    'default_tablespace_size_bytes',
+    'database_write_activity_rows',
+];
+const DECIMAL_POSTGRES_DIAGNOSTIC_KEYS = [
+    'table_health_top_risky_dead_tuple_ratio',
+];
+export const LONG_TRANSACTION_AGE_WARNING_SECONDS = 5 * 60;
+export const LONG_TRANSACTION_COUNT_WARNING_THRESHOLD = 3;
+export const IDLE_IN_TRANSACTION_AGE_WARNING_SECONDS = 5 * 60;
+export const IDLE_IN_TRANSACTION_COUNT_WARNING_THRESHOLD = 2;
+export const TABLE_HEALTH_DEAD_TUPLE_RATIO_WARNING = 0.2;
+export const TABLE_HEALTH_DEAD_TUPLE_COUNT_WARNING = 1000;
+export const UNUSED_INDEX_CANDIDATES_WARNING = 20;
+export const WAL_DIRECTORY_SIZE_WARNING_BYTES = 5 * 1024 * 1024 * 1024;
+export const TOTAL_DATABASE_SIZE_WARNING_BYTES = 50 * 1024 * 1024 * 1024;
+const allowedKeys = new Set(POSTGRES_DIAGNOSTIC_KEYS);
+export function parsePostgresDiagnostics(output) {
+    const diagnostics = {};
+    for (const rawLine of output.split(/\r?\n/iu)) {
+        const line = rawLine.trim();
+        if (!line) {
+            continue;
+        }
+        const separatorIndex = line.indexOf('|');
+        if (separatorIndex === -1) {
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const value = line.slice(separatorIndex + 1).trim();
+        if (!value || !allowedKeys.has(key)) {
+            continue;
+        }
+        diagnostics[key] = value;
+    }
+    return diagnostics;
+}
+export function renderPostgresDiagnostics(diagnostics) {
+    const connectionUtilizationPct = postgresConnectionUtilizationPct(diagnostics);
+    const parts = POSTGRES_DIAGNOSTIC_KEYS.flatMap((key) => {
+        const value = diagnostics[key];
+        const rendered = value ? [`${key}=${value}`] : [];
+        if (key === 'max_connections' && connectionUtilizationPct !== undefined) {
+            rendered.push(`connection_utilization_pct=${connectionUtilizationPct}`);
+        }
+        return rendered;
+    });
+    return parts.length > 0 ? `OK PostgreSQL diagnostics ${parts.join(' ')}` : undefined;
+}
+export function missingPostgresDiagnosticKeys(diagnostics) {
+    return REQUIRED_POSTGRES_DIAGNOSTIC_KEYS.filter((key) => diagnostics[key] === undefined);
+}
+function integerDiagnostic(value) {
+    if (!value || !/^\d+$/u.test(value)) {
+        return undefined;
+    }
+    return Number.parseInt(value, 10);
+}
+function decimalDiagnostic(value) {
+    if (!value || !/^\d+(?:\.\d+)?$/u.test(value)) {
+        return undefined;
+    }
+    return Number.parseFloat(value);
+}
+export function malformedPostgresDiagnosticKeys(diagnostics) {
+    const malformed = [];
+    for (const key of INTEGER_POSTGRES_DIAGNOSTIC_KEYS) {
+        const value = diagnostics[key];
+        if (value !== undefined && integerDiagnostic(value) === undefined) {
+            malformed.push(key);
+        }
+    }
+    for (const key of DECIMAL_POSTGRES_DIAGNOSTIC_KEYS) {
+        const value = diagnostics[key];
+        if (value !== undefined && decimalDiagnostic(value) === undefined) {
+            malformed.push(key);
+        }
+    }
+    return malformed;
+}
+export function unavailablePostgresDiagnosticsWarning(diagnostics, missingKeys) {
+    return Object.keys(diagnostics).length === 0
+        ? 'no diagnostic rows returned'
+        : `incomplete diagnostic rows: missing ${missingKeys.join(', ')}`;
+}
+export function postgresConnectionUtilizationPct(diagnostics) {
+    const connectionCount = integerDiagnostic(diagnostics.connection_count);
+    const maxConnections = integerDiagnostic(diagnostics.max_connections);
+    if (connectionCount === undefined || maxConnections === undefined || maxConnections <= 0) {
+        return undefined;
+    }
+    return Math.round((connectionCount / maxConnections) * 100);
+}
+export function postgresConnectionUtilizationWarning(diagnostics) {
+    const connectionCount = integerDiagnostic(diagnostics.connection_count);
+    const maxConnections = integerDiagnostic(diagnostics.max_connections);
+    const utilizationPct = postgresConnectionUtilizationPct(diagnostics);
+    if (connectionCount === undefined ||
+        maxConnections === undefined ||
+        utilizationPct === undefined ||
+        utilizationPct < 80) {
+        return undefined;
+    }
+    return `PostgreSQL connection utilization is high: ${utilizationPct}% of max_connections used (${connectionCount}/${maxConnections}).`;
+}
+export function postgresSlowQueryLoggingWarning(diagnostics) {
+    const slowQueryLogging = diagnostics.slow_query_logging?.trim();
+    if (!slowQueryLogging || (!/^-1\s*(?:ms)?$/iu.test(slowQueryLogging) && !/^off$/iu.test(slowQueryLogging))) {
+        return undefined;
+    }
+    return `PostgreSQL slow-query logging is disabled (log_min_duration_statement=${slowQueryLogging}). Enable it before performance triage.`;
+}
+export function postgresExtensionVisibilityWarning(diagnostics) {
+    if (diagnostics.pg_stat_statements === 'available' &&
+        diagnostics.pg_stat_statements_available_version &&
+        !diagnostics.pg_stat_statements_installed_version) {
+        return 'PostgreSQL pg_stat_statements is available but not installed. Install it before query-level performance triage.';
+    }
+    return undefined;
+}
+export function postgresLongTransactionWarning(diagnostics) {
+    const longTransactionCount = integerDiagnostic(diagnostics.long_transaction_count);
+    const oldestAgeSeconds = integerDiagnostic(diagnostics.oldest_long_transaction_age_seconds);
+    if (longTransactionCount === undefined ||
+        oldestAgeSeconds === undefined ||
+        longTransactionCount < LONG_TRANSACTION_COUNT_WARNING_THRESHOLD ||
+        oldestAgeSeconds < LONG_TRANSACTION_AGE_WARNING_SECONDS) {
+        return undefined;
+    }
+    return `PostgreSQL has ${longTransactionCount} long transaction(s) running longer than ${LONG_TRANSACTION_AGE_WARNING_SECONDS / 60} minutes (oldest ${oldestAgeSeconds}s).`;
+}
+export function postgresIdleInTransactionWarning(diagnostics) {
+    const idleTransactionCount = integerDiagnostic(diagnostics.idle_in_transaction_count);
+    const oldestAgeSeconds = integerDiagnostic(diagnostics.oldest_idle_in_transaction_age_seconds);
+    if (idleTransactionCount === undefined ||
+        oldestAgeSeconds === undefined ||
+        idleTransactionCount < IDLE_IN_TRANSACTION_COUNT_WARNING_THRESHOLD ||
+        oldestAgeSeconds < IDLE_IN_TRANSACTION_AGE_WARNING_SECONDS) {
+        return undefined;
+    }
+    return `PostgreSQL has ${idleTransactionCount} transaction(s) idle in transaction for longer than ${IDLE_IN_TRANSACTION_AGE_WARNING_SECONDS / 60} minutes (oldest ${oldestAgeSeconds}s).`;
+}
+export function postgresTableHealthWarning(diagnostics) {
+    const riskyTables = integerDiagnostic(diagnostics.table_health_risky_table_count);
+    const vacuumNeeded = integerDiagnostic(diagnostics.table_health_requires_vacuum_count);
+    const analyzeNeeded = integerDiagnostic(diagnostics.table_health_requires_analyze_count);
+    const deadTupleRatio = decimalDiagnostic(diagnostics.table_health_top_risky_dead_tuple_ratio);
+    const deadTupleCount = integerDiagnostic(diagnostics.table_health_top_risky_dead_tuple_count);
+    if (riskyTables === undefined ||
+        vacuumNeeded === undefined ||
+        analyzeNeeded === undefined ||
+        deadTupleRatio === undefined ||
+        deadTupleCount === undefined) {
+        return undefined;
+    }
+    if (deadTupleRatio < TABLE_HEALTH_DEAD_TUPLE_RATIO_WARNING || deadTupleCount < TABLE_HEALTH_DEAD_TUPLE_COUNT_WARNING) {
+        return undefined;
+    }
+    const maxRiskyRatioPercent = Math.round(deadTupleRatio * 100);
+    return `PostgreSQL table health risk: ${riskyTables} table(s) have high dead-tuple ratio; ${vacuumNeeded} table(s) need vacuum and ${analyzeNeeded} need analyze. Top risk: ${diagnostics.table_health_top_risky_table ?? 'unavailable'} (${maxRiskyRatioPercent}% dead tuples, ${deadTupleCount} dead tuples).`;
+}
+export function postgresUnusedIndexWarning(diagnostics) {
+    const candidates = integerDiagnostic(diagnostics.unused_index_candidates_count);
+    if (candidates === undefined || candidates < UNUSED_INDEX_CANDIDATES_WARNING) {
+        return undefined;
+    }
+    return `PostgreSQL has ${candidates} unused index candidates with no index scans. Review indexing strategy before adding new indexes.`;
+}
+export function postgresWalWarning(diagnostics) {
+    const walSizeBytes = integerDiagnostic(diagnostics.wal_directory_size_bytes);
+    if (walSizeBytes !== undefined && walSizeBytes >= WAL_DIRECTORY_SIZE_WARNING_BYTES) {
+        return `PostgreSQL WAL visibility warning: WAL directory is ${walSizeBytes} bytes, which is high and can increase disk pressure.`;
+    }
+    return undefined;
+}
+export function postgresCapacityWarning(diagnostics) {
+    const totalDatabaseSizeBytes = integerDiagnostic(diagnostics.total_database_size_bytes);
+    if (totalDatabaseSizeBytes === undefined || totalDatabaseSizeBytes < TOTAL_DATABASE_SIZE_WARNING_BYTES) {
+        return undefined;
+    }
+    return `PostgreSQL capacity risk: total database size is ${totalDatabaseSizeBytes} bytes. Monitor growth and WAL retention settings before disk becomes constrained.`;
+}
+export function postgresPostgresWarnings(diagnostics) {
+    const warnings = [];
+    const connectionWarning = postgresConnectionUtilizationWarning(diagnostics);
+    if (connectionWarning) {
+        warnings.push(connectionWarning);
+    }
+    const slowQueryWarning = postgresSlowQueryLoggingWarning(diagnostics);
+    if (slowQueryWarning) {
+        warnings.push(slowQueryWarning);
+    }
+    const extensionWarning = postgresExtensionVisibilityWarning(diagnostics);
+    if (extensionWarning) {
+        warnings.push(extensionWarning);
+    }
+    const longTransactionWarning = postgresLongTransactionWarning(diagnostics);
+    if (longTransactionWarning) {
+        warnings.push(longTransactionWarning);
+    }
+    const idleTransactionWarning = postgresIdleInTransactionWarning(diagnostics);
+    if (idleTransactionWarning) {
+        warnings.push(idleTransactionWarning);
+    }
+    const tableHealthWarning = postgresTableHealthWarning(diagnostics);
+    if (tableHealthWarning) {
+        warnings.push(tableHealthWarning);
+    }
+    const indexWarning = postgresUnusedIndexWarning(diagnostics);
+    if (indexWarning) {
+        warnings.push(indexWarning);
+    }
+    const walWarning = postgresWalWarning(diagnostics);
+    if (walWarning) {
+        warnings.push(walWarning);
+    }
+    const capacityWarning = postgresCapacityWarning(diagnostics);
+    if (capacityWarning) {
+        warnings.push(capacityWarning);
+    }
+    return warnings;
+}
+export function structuredPostgresDiagnostics(diagnostics) {
+    const connectionUtilizationPct = postgresConnectionUtilizationPct(diagnostics);
+    const databaseCount = integerDiagnostic(diagnostics.database_count);
+    const activeConnections = integerDiagnostic(diagnostics.active_connections);
+    const connectionCount = integerDiagnostic(diagnostics.connection_count);
+    const maxConnections = integerDiagnostic(diagnostics.max_connections);
+    const totalDatabaseSizeBytes = integerDiagnostic(diagnostics.total_database_size_bytes);
+    const largestDatabaseSizeBytes = integerDiagnostic(diagnostics.largest_database_size_bytes);
+    const tableHealthRiskyTableCount = integerDiagnostic(diagnostics.table_health_risky_table_count);
+    const tableHealthRequiresVacuumCount = integerDiagnostic(diagnostics.table_health_requires_vacuum_count);
+    const tableHealthRequiresAnalyzeCount = integerDiagnostic(diagnostics.table_health_requires_analyze_count);
+    const tableHealthTopRiskyDeadTupleRatio = decimalDiagnostic(diagnostics.table_health_top_risky_dead_tuple_ratio);
+    const tableHealthTopRiskyDeadTupleCount = integerDiagnostic(diagnostics.table_health_top_risky_dead_tuple_count);
+    const longTransactionCount = integerDiagnostic(diagnostics.long_transaction_count);
+    const oldestLongTransactionAgeSeconds = integerDiagnostic(diagnostics.oldest_long_transaction_age_seconds);
+    const idleInTransactionCount = integerDiagnostic(diagnostics.idle_in_transaction_count);
+    const oldestIdleInTransactionAgeSeconds = integerDiagnostic(diagnostics.oldest_idle_in_transaction_age_seconds);
+    const unusedIndexCandidatesCount = integerDiagnostic(diagnostics.unused_index_candidates_count);
+    const walFileCount = integerDiagnostic(diagnostics.wal_file_count);
+    const walDirectorySizeBytes = integerDiagnostic(diagnostics.wal_directory_size_bytes);
+    const defaultTablespaceSizeBytes = integerDiagnostic(diagnostics.default_tablespace_size_bytes);
+    const databaseWriteActivityRows = integerDiagnostic(diagnostics.database_write_activity_rows);
+    const structured = {
+        schemaVersion: POSTGRES_DIAGNOSTICS_CONTRACT_VERSION,
+    };
+    if (databaseCount !== undefined)
+        structured.databaseCount = databaseCount;
+    if (activeConnections !== undefined)
+        structured.activeConnections = activeConnections;
+    if (connectionCount !== undefined)
+        structured.connectionCount = connectionCount;
+    if (maxConnections !== undefined)
+        structured.maxConnections = maxConnections;
+    if (connectionUtilizationPct !== undefined)
+        structured.connectionUtilizationPct = connectionUtilizationPct;
+    if (totalDatabaseSizeBytes !== undefined)
+        structured.totalDatabaseSizeBytes = totalDatabaseSizeBytes;
+    if (diagnostics.largest_database_name) {
+        structured.largestDatabaseName = diagnostics.largest_database_name;
+    }
+    if (largestDatabaseSizeBytes !== undefined)
+        structured.largestDatabaseSizeBytes = largestDatabaseSizeBytes;
+    if (diagnostics.slow_query_logging) {
+        structured.slowQueryLogging = diagnostics.slow_query_logging;
+    }
+    if (diagnostics.pg_stat_statements) {
+        structured.pgStatStatements = diagnostics.pg_stat_statements;
+    }
+    if (diagnostics.pg_stat_statements_available_version) {
+        structured.pgStatStatementsAvailableVersion = diagnostics.pg_stat_statements_available_version;
+    }
+    if (diagnostics.pg_stat_statements_installed_version) {
+        structured.pgStatStatementsInstalledVersion = diagnostics.pg_stat_statements_installed_version;
+    }
+    if (diagnostics.shared_preload_libraries) {
+        structured.sharedPreloadLibraries = diagnostics.shared_preload_libraries;
+    }
+    if (diagnostics.shared_buffers) {
+        structured.sharedBuffers = diagnostics.shared_buffers;
+    }
+    if (longTransactionCount !== undefined) {
+        structured.longTransactionCount = longTransactionCount;
+    }
+    if (oldestLongTransactionAgeSeconds !== undefined) {
+        structured.oldestLongTransactionAgeSeconds = oldestLongTransactionAgeSeconds;
+    }
+    if (idleInTransactionCount !== undefined) {
+        structured.idleInTransactionCount = idleInTransactionCount;
+    }
+    if (oldestIdleInTransactionAgeSeconds !== undefined) {
+        structured.oldestIdleInTransactionAgeSeconds = oldestIdleInTransactionAgeSeconds;
+    }
+    if (tableHealthRiskyTableCount !== undefined) {
+        structured.tableHealthRiskyTableCount = tableHealthRiskyTableCount;
+    }
+    if (tableHealthRequiresVacuumCount !== undefined) {
+        structured.tableHealthRequiresVacuumCount = tableHealthRequiresVacuumCount;
+    }
+    if (tableHealthRequiresAnalyzeCount !== undefined) {
+        structured.tableHealthRequiresAnalyzeCount = tableHealthRequiresAnalyzeCount;
+    }
+    if (diagnostics.table_health_top_risky_table) {
+        structured.tableHealthTopRiskyTable = diagnostics.table_health_top_risky_table;
+    }
+    if (tableHealthTopRiskyDeadTupleRatio !== undefined) {
+        structured.tableHealthTopRiskyDeadTupleRatio = tableHealthTopRiskyDeadTupleRatio;
+    }
+    if (tableHealthTopRiskyDeadTupleCount !== undefined) {
+        structured.tableHealthTopRiskyDeadTupleCount = tableHealthTopRiskyDeadTupleCount;
+    }
+    if (unusedIndexCandidatesCount !== undefined) {
+        structured.unusedIndexCandidatesCount = unusedIndexCandidatesCount;
+    }
+    if (diagnostics.wal_level) {
+        structured.walLevel = diagnostics.wal_level;
+    }
+    if (diagnostics.wal_archive_mode) {
+        structured.walArchiveMode = diagnostics.wal_archive_mode;
+    }
+    if (walFileCount !== undefined) {
+        structured.walFileCount = walFileCount;
+    }
+    if (walDirectorySizeBytes !== undefined) {
+        structured.walDirectorySizeBytes = walDirectorySizeBytes;
+    }
+    if (defaultTablespaceSizeBytes !== undefined) {
+        structured.defaultTablespaceSizeBytes = defaultTablespaceSizeBytes;
+    }
+    if (databaseWriteActivityRows !== undefined) {
+        structured.databaseWriteActivityRows = databaseWriteActivityRows;
+    }
+    return structured;
+}

package/docs/generated-environment-verification.md

@@ -23,7 +23,7 @@ not validate staging or production deployments.
 | Doctor checks | Metadata, compose files, scripts, source repo paths, and local tooling checks behave as expected. | `npx @wpmoo/toolkit doctor` or `./moo doctor` |
 | Doctor safe fixes | Safe file-level fixes are applied only with `--fix`, then doctor runs again and reports any remaining manual issues. | `npx @wpmoo/toolkit doctor --fix` |
 | Generated Postgres checks | For PostgreSQL 18 environments, doctor validates db mount targets avoid old PG image-specific paths and can normalize safe targets with `--fix`. | `npx @wpmoo/toolkit doctor`, `npx @wpmoo/toolkit doctor --fix` |
-| PostgreSQL diagnostics | Optional read-only database health/performance diagnostics report database count, sessions currently running queries with `pg_stat_activity.state = 'active'`, total database size, slow-query readiness, extension visibility, and selected settings without failing doctor when the database is unavailable. | `npx @wpmoo/toolkit doctor --postgres`, `npx @wpmoo/toolkit doctor --json --postgres` |
+| PostgreSQL diagnostics | Optional read-only, advisory-only database health and performance diagnostics (no automatic tuning), covering active/idle-in-transaction sessions, table health signals, WAL/capacity context, unused-index hints, and slow-query readiness. JSON mode emits a versioned PostgreSQL contract with optional fields when a metric is unavailable. | `npx @wpmoo/toolkit doctor --postgres`, `npx @wpmoo/toolkit doctor --json --postgres` |
 | Source repo add/remove | Source repository registration and submodule lifecycle behave correctly. | `npx @wpmoo/toolkit add-repo ...`, `npx @wpmoo/toolkit remove-repo ...` |
 | Source manifest sync | Source repo metadata, `.gitmodules`, and `odoo/custom/manifests/sources.yaml` stay aligned. | `npx @wpmoo/toolkit source list`, `npx @wpmoo/toolkit source sync` |
 | Module add/remove | Module skeleton files include manifest, model, access CSV, explicit view XML, action/menu XML, post-install test scaffold, and selected source repo registration. Existing scaffold files are not overwritten. | `npx @wpmoo/toolkit add-module ...`, `npx @wpmoo/toolkit remove-module ...` |
@@ -76,16 +76,16 @@ is involved, use PostgreSQL upgrade tooling first.
 
 Use `doctor --postgres` when the database container is running and you want
 read-only PostgreSQL diagnostics. The check uses fixed diagnostic queries for
-database count, sessions currently running queries where
-`pg_stat_activity.state` is `active`, aggregate database size, slow-query
-logging readiness,
-`pg_stat_statements` availability, and `shared_buffers`. If the database is
-unavailable, doctor reports a warning instead of failing the whole environment
-check.
-JSON output preserves `checks` and `warnings` while adding a structured
-`postgres` object when `--postgres` is requested.
-Incomplete or malformed PostgreSQL metric rows are reported as unavailable
-diagnostics.
+database count, sessions currently running queries where `pg_stat_activity.state`
+is `active`, long transactions / idle-in-transaction sessions, table health
+signals, unused index advisor signals, WAL and capacity visibility, and
+slow-query logging readiness (`log_min_duration_statement` and
+`pg_stat_statements` visibility). If the database is unavailable, doctor reports
+a warning instead of failing the whole environment check.
+
+`doctor --json --postgres` keeps output stable by exposing a versioned PostgreSQL
+diagnostics contract. The contract is intentionally permissive: fields are optional
+and omitted or marked unavailable when a running database does not expose them.
 
 ## Safe reset policy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpmoo/toolkit",
-  "version": "0.9.26",
+  "version": "0.9.27",
   "description": "WPMoo Toolkit for development, staging, and production lifecycle workflows.",
   "type": "module",
   "repository": {