@wpmoo/toolkit 0.9.9 → 0.9.11

package/README.md

@@ -144,6 +144,10 @@ Every cockpit action maps to a direct command, so the same workflow can be used
 ./moo restore-snapshot --dry-run before-update devel
 ```
 
+In `WPMOO_ENV=prod`, `install`, `update`, and `test` require `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
+`resetdb` and real `restore-snapshot` require `WPMOO_ALLOW_DESTRUCTIVE=1` in `stage` and `prod`.
+`restore-snapshot --dry-run` remains allowed for preview.
+
 Module source actions also have direct commands. Default is `private`; pass `--source-type oca` or `--source-type external` for non-private source repositories:
 
 ```bash
@@ -166,9 +170,11 @@ 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, active connections, slow-query readiness, extension
-visibility, and settings.
+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 --json --postgres` includes a structured `postgres` object for automation.
+Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
 ## Documentation
 

package/dist/daily-actions.js

@@ -155,9 +155,15 @@ function isDestructiveCommand(command, args) {
         return true;
     return command === 'restore-snapshot' && args[0] !== '--dry-run';
 }
+function isProductionLifecycleCommand(command) {
+    return command === 'install' || command === 'update' || command === 'test';
+}
 function destructiveCommandError(command, envName) {
     return `Refusing destructive command '${command}' in WPMOO_ENV=${envName}. Set WPMOO_ALLOW_DESTRUCTIVE=1 to run it intentionally.`;
 }
+function productionLifecycleCommandError(command) {
+    return `Refusing production lifecycle command '${command}' in WPMOO_ENV=prod. Set WPMOO_ALLOW_PROD_LIFECYCLE=1 to run it intentionally.`;
+}
 async function assertDestructiveCommandAllowed(command, args, cwd) {
     if (!isDestructiveCommand(command, args)) {
         return;
@@ -172,6 +178,20 @@ async function assertDestructiveCommandAllowed(command, args, cwd) {
         throw new Error(destructiveCommandError(command, envName));
     }
 }
+async function assertProductionLifecycleCommandAllowed(command, cwd) {
+    if (!isProductionLifecycleCommand(command)) {
+        return;
+    }
+    const env = await readEnvFile(cwd);
+    const envName = process.env.WPMOO_ENV?.trim() || selectedComposeEnvironment(env);
+    if (envName !== 'prod') {
+        return;
+    }
+    const allowProdLifecycle = process.env.WPMOO_ALLOW_PROD_LIFECYCLE?.trim() || env?.get('WPMOO_ALLOW_PROD_LIFECYCLE')?.trim();
+    if (allowProdLifecycle !== '1') {
+        throw new Error(productionLifecycleCommandError(command));
+    }
+}
 async function assertEnvironmentRoot(cwd) {
     try {
         await access(join(cwd, markerPath));
@@ -194,6 +214,7 @@ export async function dailyActionPlan(command, argv, cwd = process.cwd()) {
     await assertEnvironmentRoot(cwd);
     const scriptPath = await assertScriptExists(cwd, dailyActionScripts[command]);
     const args = scriptArgs(command, argv);
+    await assertProductionLifecycleCommandAllowed(command, cwd);
     await assertDestructiveCommandAllowed(command, args, cwd);
     return {
         cwd,

package/dist/doctor.js

@@ -55,6 +55,16 @@ WITH metrics(metric, value) AS (
   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
@@ -82,16 +92,20 @@ FROM metrics
 ORDER BY CASE metric
   WHEN 'database_count' THEN 1
   WHEN 'active_connections' THEN 2
-  WHEN 'total_database_size_bytes' THEN 3
-  WHEN 'slow_query_logging' THEN 4
-  WHEN 'pg_stat_statements' THEN 5
-  WHEN 'shared_buffers' THEN 6
+  WHEN 'connection_count' THEN 3
+  WHEN 'max_connections' THEN 4
+  WHEN 'total_database_size_bytes' THEN 5
+  WHEN 'slow_query_logging' THEN 6
+  WHEN 'pg_stat_statements' THEN 7
+  WHEN 'shared_buffers' THEN 8
   ELSE 99
 END;
 `.trim();
 const postgresDiagnosticKeys = [
     'database_count',
     'active_connections',
+    'connection_count',
+    'max_connections',
     'total_database_size_bytes',
     'slow_query_logging',
     'pg_stat_statements',
@@ -126,27 +140,79 @@ function parsePostgresDiagnostics(output) {
     return diagnostics;
 }
 function renderPostgresDiagnostics(diagnostics) {
+    const connectionUtilizationPct = postgresConnectionUtilizationPct(diagnostics);
     const parts = postgresDiagnosticKeys.flatMap((key) => {
         const value = diagnostics[key];
-        return value ? [`${key}=${value}`] : [];
+        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 postgresDiagnosticKeys.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',
+    ];
+    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 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);
     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.slow_query_logging)
@@ -555,22 +621,32 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
     if (actualOptions.postgres) {
         try {
             const postgresDiagnostics = await readPostgresDiagnostics(target, actualRunner);
-            const renderedPostgresDiagnostics = renderPostgresDiagnostics(postgresDiagnostics);
-            if (renderedPostgresDiagnostics) {
-                checks.push(renderedPostgresDiagnostics);
+            const missingKeys = missingPostgresDiagnosticKeys(postgresDiagnostics);
+            const malformedKeys = malformedPostgresDiagnosticKeys(postgresDiagnostics);
+            if (missingKeys.length === 0 && malformedKeys.length === 0) {
+                const renderedPostgresDiagnostics = renderPostgresDiagnostics(postgresDiagnostics);
+                if (renderedPostgresDiagnostics) {
+                    checks.push(renderedPostgresDiagnostics);
+                }
                 report.postgres = {
                     requested: true,
                     available: true,
                     diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
                 };
+                const connectionUtilizationWarning = postgresConnectionUtilizationWarning(postgresDiagnostics);
+                if (connectionUtilizationWarning) {
+                    warnings.push(connectionUtilizationWarning);
+                }
             }
             else {
-                const warning = 'no diagnostic rows returned';
+                const warning = malformedKeys.length > 0
+                    ? `malformed diagnostic values: ${malformedKeys.join(', ')}`
+                    : unavailablePostgresDiagnosticsWarning(postgresDiagnostics, missingKeys);
                 warnings.push(`PostgreSQL diagnostics unavailable: ${warning}`);
                 report.postgres = {
                     requested: true,
                     available: false,
-                    diagnostics: {},
+                    diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
                     warning,
                 };
             }

package/dist/external-templates.js

@@ -43,6 +43,8 @@ export function renderComposeEnvExample(options) {
         '# Required only when intentionally running destructive database actions',
         '# such as resetdb or restore-snapshot with WPMOO_ENV=stage or WPMOO_ENV=prod.',
         '# WPMOO_ALLOW_DESTRUCTIVE=1',
+        '# Required only when intentionally running install/update/test in WPMOO_ENV=prod.',
+        '# WPMOO_ALLOW_PROD_LIFECYCLE=1',
         '',
     ].join('\n');
 }

package/dist/help.js

@@ -85,6 +85,11 @@ Daily actions:
   Generated environments also include ./moo for local compose commands such as ./moo start.
   Use ./moo or npx @wpmoo/toolkit with the same daily action arguments.
 
+Production command guards:
+  In WPMOO_ENV=prod, install/update/test require WPMOO_ALLOW_PROD_LIFECYCLE=1.
+  resetdb and real restore-snapshot require WPMOO_ALLOW_DESTRUCTIVE=1 in stage/prod.
+  restore-snapshot --dry-run remains allowed for preview.
+
 Cockpit:
   Run npx @wpmoo/toolkit inside a generated environment to open the cockpit.
   Use Command palette / to search slash commands across services, modules, database,
@@ -104,7 +109,10 @@ Status and doctor:
   doctor: deeper health check. May check Docker CLI access and GitHub workflows.
   doctor --fix: applies safe file-level repairs. Runs doctor again after fixes.
   doctor --postgres: adds read-only PostgreSQL diagnostics such as database size,
-    active connections, slow-query readiness, extension visibility, and settings.
+    sessions currently running queries with pg_stat_activity.state = 'active',
+    connection utilization against max_connections, slow-query readiness,
+    extension visibility, and settings.
+    Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
 Task recipes:
   Create environment:
@@ -148,6 +156,7 @@ Machine-readable JSON output:
     npx @wpmoo/toolkit source sync --json
     npx @wpmoo/toolkit doctor --json
     doctor --json --postgres includes a structured postgres object for automation.
+    Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
 Example:
   npx @wpmoo/toolkit create \\

package/dist/templates.js

@@ -208,6 +208,10 @@ resources/odoo/entrypoint.sh
 
 Development uses compose.yaml plus compose/dev.yaml by default.
 Set WPMOO_ENV=stage or WPMOO_ENV=prod only after providing production-grade secrets and volumes.
+In WPMOO_ENV=prod, module lifecycle commands such as install, update, and test
+require WPMOO_ALLOW_PROD_LIFECYCLE=1. Destructive database commands such as
+resetdb and real restore-snapshot require WPMOO_ALLOW_DESTRUCTIVE=1 in stage
+and prod. restore-snapshot --dry-run remains available for preview.
 
 If copied from the standalone resource, additional compose notes are in
 \`docs/compose.md\`.
@@ -568,6 +572,23 @@ require_destructive_allowed() {
   fi
 }
 
+allow_prod_lifecycle() {
+  local value="\${WPMOO_ALLOW_PROD_LIFECYCLE:-$(env_file_value WPMOO_ALLOW_PROD_LIFECYCLE)}"
+  [[ "$value" == "1" ]]
+}
+
+require_prod_lifecycle_allowed() {
+  local command="$1"
+  local env_name
+  env_name="$(selected_env)"
+  if [[ "$env_name" == "prod" ]]; then
+    if ! allow_prod_lifecycle; then
+      echo "Refusing production lifecycle command '$command' in WPMOO_ENV=prod. Set WPMOO_ALLOW_PROD_LIFECYCLE=1 to run it intentionally." >&2
+      exit 1
+    fi
+  fi
+}
+
 run_script() {
   local script="$1"
   shift
@@ -613,16 +634,19 @@ case "$command" in
   "install")
     shift
     require_module_args "$command" "$@"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/install.sh "$@"
     ;;
   "update")
     shift
     require_module_args "$command" "$@"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/update.sh "$@"
     ;;
   "test")
     shift
     validate_test_args "$@"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/test.sh "$@"
     ;;
   "resetdb")

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, active connections, 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 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` |
 | 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 ...` |
@@ -53,6 +53,12 @@ scripts unless `.env` or the process environment explicitly sets
 `WPMOO_ALLOW_DESTRUCTIVE=1`. `restore-snapshot --dry-run` remains allowed for
 safe preview.
 
+When `WPMOO_ENV=prod`, WPMoo also refuses module lifecycle commands that mutate
+or exercise the Odoo database (`install`, `update`, and `test`) unless `.env` or
+the process environment explicitly sets `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
+Staging keeps these commands available for release rehearsal while still
+enforcing the destructive database guard above.
+
 For PostgreSQL 18 environments (including `POSTGRES_IMAGE=postgres:18`), ensure db
 volume and tmpfs mount targets use `/var/lib/postgresql` directly:
 
@@ -70,12 +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, active connections, 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.
+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.
 
 ## Safe reset policy
 

package/package.json

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