@wpmoo/toolkit 0.9.26 → 0.9.28

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
 
@@ -203,8 +222,12 @@ warning while keeping the scoped package release valid.
 
 ## Documentation
 
+- [Command Reference](docs/command-reference.md)
 - [External Resources](docs/external-resources.md)
 - [Generated Environment Verification](docs/generated-environment-verification.md)
+- [Lifecycle Recipes](docs/lifecycle-recipes.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [1.0 Readiness](docs/1-0-readiness.md)
 - Public documentation site: <https://wpmoo.org>
 
 ## License

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,