@wpmoo/toolkit 0.9.31 → 0.9.33

package/README.md

@@ -143,6 +143,9 @@ Every cockpit action maps to a direct command, so the same workflow can be used
 
 When an environment has many module candidates, module selection switches to
 search so names, repositories, and source categories can be filtered quickly.
+Runtime actions that need running services or a ready database are disabled in
+the cockpit until the environment is ready; file-only actions such as module
+scaffolding, source repository changes, and safe reset remain available.
 
 ```bash
 ./moo start
@@ -181,6 +184,9 @@ npx @wpmoo/toolkit doctor --json --postgres
 ```
 
 JSON output is optional; human-readable output remains the default.
+`doctor --json --fix` is intentionally unsupported because `doctor --fix` may
+write safe file-level repairs. Run `doctor --fix` first, then `doctor --json`
+to inspect the post-fix state.
 Human `doctor` output is grouped into stable sections (`Generated files`,
 `Compose`, `Source repositories`, `PostgreSQL`, and `Host tools`) so terminal
 operators can see which lifecycle layer needs attention first.
@@ -212,6 +218,10 @@ JSON variant exposes a versioned PostgreSQL diagnostics contract.
 `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.
+Optional PostgreSQL probe permission failures appear under
+`postgres.optionalProbeFailures` when available; they do not make
+`postgres.available` false and can be ignored by automation that only needs core
+diagnostics.
 All `doctor --json` reports also include optional `sections` entries that group
 checks, warnings, and errors without changing the legacy flat arrays.
 
@@ -244,7 +254,9 @@ warning while keeping the scoped package release valid.
   rejects it, the release still succeeds as long as the three required scoped
   packages are valid.
 - **Smoke expectation**: run `npm run smoke:published -- "$VERSION"` after the
-  release tag workflow completes.
+  release tag workflow completes. The script prints `Smoke step:` progress lines
+  before each published CLI check so slow registry-backed `npx` resolution is
+  visible.
 - **Deterministic smoke target**: pin the target package explicitly so smoke checks
   are reproducible across reruns:
 

package/dist/cockpit/menu.js

@@ -21,6 +21,16 @@ const topLevelCategoryOrder = [
 const topLevelCommands = topLevelCategoryOrder.flatMap((category) => cockpitCommands.filter((command) => command.category === category && command.id !== 'exit'));
 const topLevelCommandLabelWidth = Math.max(...topLevelCommands.map((command) => command.label.length));
 const moduleDependentCommandIds = new Set(['list-modules', 'install', 'update', 'test', 'pot', 'remove-module']);
+const runningServicesRequiredCommandIds = new Set([
+    'install',
+    'update',
+    'test',
+    'pot',
+    'psql',
+    'snapshot',
+    'restore-snapshot',
+    'resetdb',
+]);
 function rgb(red, green, blue, value) {
     return `\u001B[38;2;${red};${green};${blue}m${value}\u001B[39m`;
 }
@@ -39,6 +49,7 @@ const disabledReasonNextStep = {
     'Services stopped.': 'Next: choose "Start services" first.',
     'Already running.': 'Next: choose "Stop services" or "Restart services".',
     'Docker not running.': 'Next: start Docker, then choose "Start services".',
+    'Database not ready.': 'Next: wait for the database or choose "Restart services".',
     'No source repos found.': 'Next: choose "Add source repo" first.',
 };
 function disabledError(reason) {
@@ -50,15 +61,22 @@ function disabledError(reason) {
     return nextStep ? `${base}\nReason: ${reason}\n${nextStep}` : `${base}\nReason: ${reason}`;
 }
 function serviceDisabledReason(command, serviceStatus) {
-    if (command.category !== 'services' || !serviceStatus)
+    if (!serviceStatus)
+        return undefined;
+    const requiresRunningServices = command.category === 'services' || runningServicesRequiredCommandIds.has(command.id);
+    if (!requiresRunningServices)
         return undefined;
     if (serviceStatus.kind === 'docker-not-running')
         return 'Docker not running.';
     if (serviceStatus.kind === 'running' && command.id === 'start')
         return 'Already running.';
-    if (serviceStatus.kind === 'stopped' && ['stop', 'restart', 'logs', 'shell'].includes(command.id)) {
+    if (serviceStatus.kind === 'stopped' &&
+        (['stop', 'restart', 'logs', 'shell'].includes(command.id) || runningServicesRequiredCommandIds.has(command.id))) {
         return 'Services stopped.';
     }
+    if (serviceStatus.kind === 'services-running' && runningServicesRequiredCommandIds.has(command.id)) {
+        return 'Database not ready.';
+    }
     return undefined;
 }
 function moduleDisabledReason(command, moduleCount) {
@@ -71,10 +89,10 @@ function snapshotDisabledReason(command, snapshotCount) {
     return snapshotCount === 0 && command.id === 'restore-snapshot' ? 'No snapshots found.' : undefined;
 }
 function disabledReason(command, serviceStatus, moduleCount, sourceRepoCount, snapshotCount) {
-    return (serviceDisabledReason(command, serviceStatus) ??
-        moduleDisabledReason(command, moduleCount) ??
+    return (moduleDisabledReason(command, moduleCount) ??
         sourceRepoDisabledReason(command, sourceRepoCount) ??
-        snapshotDisabledReason(command, snapshotCount));
+        snapshotDisabledReason(command, snapshotCount) ??
+        serviceDisabledReason(command, serviceStatus));
 }
 function commandDisabledValue(reason) {
     if (!reason) {

package/dist/doctor.js

@@ -115,6 +115,13 @@ function postgresDiagnosticsTimeoutMs(options) {
         ? options.postgresTimeoutMs
         : defaultPostgresDiagnosticsTimeoutMs;
 }
+function optionalPostgresProbeFailureWarning(error) {
+    const message = commandErrorText(error).trim();
+    if (!/(?:permission denied|insufficient privilege|must be superuser|not permitted|not allowed)/iu.test(message)) {
+        return undefined;
+    }
+    return message.split(/\r?\n/u).find((line) => line.trim())?.trim();
+}
 async function readPostgresDiagnosticQuery(target, runner, query, timeoutMs) {
     const queryLiteral = JSON.stringify(query);
     const command = [
@@ -127,16 +134,21 @@ async function readPostgresDiagnosticQuery(target, runner, query, timeoutMs) {
 }
 async function readPostgresDiagnostics(target, runner, timeoutMs) {
     const diagnostics = await readPostgresDiagnosticQuery(target, runner, POSTGRES_DIAGNOSTICS_QUERY, timeoutMs);
+    const optionalProbeFailures = [];
     for (const probe of POSTGRES_DIAGNOSTICS_OPTIONAL_QUERIES) {
         try {
             Object.assign(diagnostics, await readPostgresDiagnosticQuery(target, runner, probe.query, timeoutMs));
         }
-        catch {
+        catch (error) {
+            const warning = optionalPostgresProbeFailureWarning(error);
+            if (warning) {
+                optionalProbeFailures.push({ id: probe.id, warning });
+            }
             // Optional probes use PostgreSQL functions that can require elevated roles.
             // Their failure must not hide the core read-only health report.
         }
     }
-    return diagnostics;
+    return { diagnostics, optionalProbeFailures };
 }
 function stripInlineComment(line) {
     const hashIndex = line.indexOf('#');
@@ -628,7 +640,7 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
     }
     if (actualOptions.postgres) {
         try {
-            const postgresDiagnostics = await readPostgresDiagnostics(target, actualRunner, postgresDiagnosticsTimeoutMs(actualOptions));
+            const { diagnostics: postgresDiagnostics, optionalProbeFailures } = await readPostgresDiagnostics(target, actualRunner, postgresDiagnosticsTimeoutMs(actualOptions));
             const missingKeys = missingPostgresDiagnosticKeys(postgresDiagnostics);
             const malformedKeys = malformedPostgresDiagnosticKeys(postgresDiagnostics);
             if (missingKeys.length === 0 && malformedKeys.length === 0) {
@@ -641,6 +653,7 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
                     contractVersion: POSTGRES_DIAGNOSTICS_CONTRACT_VERSION,
                     available: true,
                     diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
+                    ...(optionalProbeFailures.length > 0 ? { optionalProbeFailures } : {}),
                 };
                 warnings.push(...postgresPostgresWarnings(postgresDiagnostics));
             }
@@ -654,6 +667,7 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
                     contractVersion: POSTGRES_DIAGNOSTICS_CONTRACT_VERSION,
                     available: false,
                     diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
+                    ...(optionalProbeFailures.length > 0 ? { optionalProbeFailures } : {}),
                     warning,
                 };
             }

package/dist/help.js

@@ -161,6 +161,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.
+    doctor --json is read-only; run doctor --fix first, then doctor --json for post-fix state.
     Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
 JSON compatibility policy:

package/docs/command-reference.md

@@ -29,6 +29,12 @@ unscoped `npx wpmoo` short alias is optional and best-effort; scripts should use
 
 Run these from the generated environment root:
 
+The cockpit disables runtime actions such as `psql`, `snapshot`, `resetdb`,
+`restore-snapshot`, `install`, `update`, `test`, and `pot` while services are
+stopped or the database is not ready. File-only cockpit actions remain
+selectable so source repositories, module scaffolds, and safe reset can still be
+managed.
+
 | Command | Cockpit Equivalent | Guarded In Stage/Prod | Notes |
 | --- | --- | --- | --- |
 | `./moo start` | Services -> Start services | No | Starts local Odoo services. Disabled in cockpit when already running. |
@@ -66,9 +72,15 @@ Current JSON contract notes:
 - `status --json` uses `schemaVersion: 1`.
 - `source list --json` and `source sync --json` use `schemaVersion: 1`.
 - `doctor --json` uses `schemaVersion: 1`.
+- `doctor --json --fix` is intentionally unsupported because `doctor --fix`
+  may mutate files. Run `doctor --fix` first, then `doctor --json` to inspect
+  post-fix state.
 - `doctor --json --postgres` adds `postgres.contractVersion` and a PostgreSQL
   diagnostics object with its own `schemaVersion`.
 - PostgreSQL fields are optional when a metric is unavailable.
+- Optional privileged PostgreSQL probe failures may appear under
+  `postgres.optionalProbeFailures`; core diagnostics remain available when those
+  optional probes fail with permission errors.
 - Automation should ignore unknown JSON fields.
 - Minor and patch releases may add optional fields without a breaking release.
 - Removing, renaming, or changing the meaning of a documented field requires a

package/docs/handoff.md

@@ -70,6 +70,9 @@ pre-existing global `NPM_CONFIG_CACHE` state unless you intentionally reuse it.
 
 The smoke script checks `--version`, top-level `--help`, and critical command
 help output before optional generated-environment acceptance smoke.
+Long registry-backed smoke runs print `Smoke step:` progress lines before each
+published CLI check, so a slow `npx` or `npm exec` resolution is visible in the
+terminal instead of appearing stuck.
 
 For a 1.0.0 tag, run generated-environment acceptance smoke with
 WPMOO_SMOKE_ENVIRONMENT=1. Treat the release as final only after that smoke

package/docs/troubleshooting.md

@@ -11,6 +11,8 @@ Symptoms:
 - The create wizard stops before writing files.
 - `./moo start`, `./moo status`, or `./moo doctor` reports Docker or Docker
   Compose as unavailable.
+- The cockpit disables database or module runtime actions because Docker,
+  services, or the database are not ready.
 
 Check:
 
@@ -30,6 +32,9 @@ The create wizard intentionally stops before setup questions when required
 runtime tools are missing. That protects the workspace from half-created
 environments.
 
+If Docker is running but the cockpit says the database is not ready, wait for
+PostgreSQL readiness or choose `Restart services`.
+
 ## No Modules Found
 
 Symptoms:

package/package.json

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