@wpmoo/toolkit 0.9.31 → 0.9.32

package/README.md

@@ -181,6 +181,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 +215,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 +251,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/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

@@ -66,9 +66,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/package.json

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