@wpmoo/toolkit 0.9.29 → 0.9.30

package/docs/command-reference.md

@@ -42,7 +42,7 @@ Run these from the generated environment root:
 | `./moo test <module[,module]> --db <db>` | Modules -> Run tests | Yes in prod | Runs Odoo tests for modules. |
 | `./moo lint` | Modules -> Run environment lint | No | Runs configured environment lint checks. |
 | `./moo pot <module[,module]> [db] [output]` | Modules -> Generate POT | No | Generates translation template files. |
-| `./moo snapshot [db] [name]` | Database -> Create snapshot | No | Creates a database and filestore snapshot. |
+| `./moo snapshot [--list] [db] [name]` | Database -> Create snapshot | No | Creates a database and filestore snapshot, or lists known snapshots with `--list`. |
 | `./moo restore-snapshot --dry-run <name> [db]` | Database -> Restore snapshot | Preview only | Prints a restore preview without changing data. |
 | `./moo restore-snapshot <name> [db]` | Database -> Restore snapshot | Yes | Restores database and filestore from a snapshot. |
 | `./moo resetdb [db] [module[,module]]` | Database -> Reset database | Yes | Destructive database reset. |
@@ -88,6 +88,24 @@ Current JSON contract notes:
 
 Process environment values take precedence over `.env` values for safety flags.
 
+## Approval Ledger
+
+For time-bounded local approvals, add JSONL entries to `.wpmoo/approvals.jsonl`.
+Generated `.gitignore` ignores this file, and it should not be committed.
+Existing `WPMOO_ALLOW_*` flags remain supported; ledger entries are an additive
+way to make short-lived intent explicit.
+
+Each line is one JSON object:
+
+```json
+{"scope":"stage-lifecycle","environment":"stage","command":"install","expiresAt":"2026-05-21T12:30:00.000Z","reason":"release rehearsal"}
+```
+
+Supported `scope` values are `stage-lifecycle`, `prod-lifecycle`,
+`destructive`, `no-recent-snapshot`, and `migration-risk`. `environment` must be
+`stage` or `prod`. `command` is optional; omit it only for a deliberately broad
+approval. Expired, malformed, or mismatched entries are ignored.
+
 ## Exit Behavior
 
 - Successful commands exit `0`.

package/docs/generated-environment-verification.md

@@ -59,6 +59,11 @@ 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.
 
+Generated environments also honor time-bounded local approvals from
+`.wpmoo/approvals.jsonl`. Generated `.gitignore` ignores this ledger and
+can approve the same scopes as the environment flags for a specific stage/prod
+command until `expiresAt`.
+
 For PostgreSQL 18 environments (including `POSTGRES_IMAGE=postgres:18`), ensure db
 volume and tmpfs mount targets use `/var/lib/postgresql` directly:
 
@@ -80,12 +85,18 @@ 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.
+`pg_stat_statements` visibility). It also surfaces read-only PostgreSQL
+configuration visibility for `shared_buffers`, `work_mem`,
+`maintenance_work_mem`, `effective_cache_size`, and `shared_preload_libraries`.
+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.
+The broader `doctor --json` payload also includes optional `sections` entries
+that group checks, warnings, and errors by generated files, compose, source
+repositories, PostgreSQL, and host tools while preserving the legacy flat arrays.
 
 ## Safe reset policy
 
@@ -114,6 +125,13 @@ odoo/custom/manifests/
 Run `npx @wpmoo/toolkit reset --dry-run` before writing changes when you need to
 review the generated file refresh plan.
 
+Pre-1.0 environments that still use `odoo/custom/src/<repo>` source folders are
+treated as legacy private sources. `doctor` reports the migration path when
+metadata is missing, and safe reset can register those folders in
+`.wpmoo/odoo.json` plus `odoo/custom/manifests/sources.yaml` without deleting the
+existing source folder. Module listing also reads the legacy folder while users
+move it to `odoo/custom/src/private/<repo>` at their own pace.
+
 ## Snapshot policy
 
 Use restore preview before a destructive restore:
@@ -122,6 +140,9 @@ Use restore preview before a destructive restore:
 ./moo restore-snapshot --dry-run <snapshot-name> [db]
 ```
 
+Use `./moo snapshot --list` to inspect known snapshot names, created times,
+database hints, dump paths, and filestore presence before selecting one.
+
 `WPMOO_SNAPSHOT_RETENTION_COUNT` may be set to a positive integer to prune old
 snapshot manifests and their matching dump/filestore files after a new snapshot
 is written.

package/docs/handoff.md

@@ -33,6 +33,10 @@ The optional `wpmoo` short alias is warning-only. If npm returns `E404` or
 otherwise rejects that alias, the release remains valid when the required
 scoped packages publish and verify correctly.
 
+Smoke checks should be deterministic by always pinning the version you are
+verifying, and by using one pinned package entrypoint for each artifact you
+validate.
+
 Verify a tagged release with:
 
 ```bash
@@ -57,15 +61,23 @@ Optional short alias rule:
 Suggested smoke check:
 
 ```bash
-npm run smoke:published -- "$VERSION"
+WPMOO_PUBLISHED_PACKAGE_SPEC="@wpmoo/toolkit@$VERSION" \
+  npm run smoke:published -- "$VERSION"
 ```
 
+For full release reproducibility, keep the default package cache behavior and avoid
+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.
+
 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
 passes:
 
 ```bash
-WPMOO_SMOKE_ENVIRONMENT=1 npm run smoke:published -- "$VERSION"
+WPMOO_SMOKE_ENVIRONMENT=1 WPMOO_PUBLISHED_PACKAGE_SPEC="@wpmoo/toolkit@$VERSION" \
+  npm run smoke:published -- "$VERSION"
 ```
 
 Current command standard:

package/docs/lifecycle-recipes.md

@@ -125,6 +125,12 @@ Take a snapshot before risky changes:
 ./moo snapshot devel before-moo-test-update
 ```
 
+List available snapshots before choosing one:
+
+```bash
+./moo snapshot --list
+```
+
 Preview a restore:
 
 ```bash
@@ -187,4 +193,3 @@ WPMOO_ENV=prod WPMOO_ALLOW_DESTRUCTIVE=1 ./moo restore-snapshot before-change de
 
 Do not set production flags globally in a shell profile. Prefer one-command
 environment variable prefixes so intent is visible in shell history.
-

package/docs/troubleshooting.md

@@ -151,6 +151,33 @@ Use the supported package path in automation:
 npx @wpmoo/toolkit --version
 ```
 
+## Published Smoke Is Not Reproducible
+
+Symptoms:
+
+- Smoke succeeds once and fails later, or output differs between runs.
+- The smoke step fails on one environment but not another with the same tag.
+
+Use an explicit package spec so each smoke run uses the same published package
+artifact:
+
+```bash
+VERSION="$(node -p "require('./package.json').version")"
+WPMOO_PUBLISHED_PACKAGE_SPEC="@wpmoo/toolkit@$VERSION" \
+  npm run smoke:published -- "$VERSION"
+```
+
+That script runs in temporary directories and uses a temporary npm cache when
+`NPM_CONFIG_CACHE` is not already set. Set a fixed cache path only when you need
+to reproduce with a shared cache.
+
+For `1.0.0`, include generated-environment acceptance smoke:
+
+```bash
+WPMOO_SMOKE_ENVIRONMENT=1 WPMOO_PUBLISHED_PACKAGE_SPEC="@wpmoo/toolkit@$VERSION" \
+  npm run smoke:published -- "$VERSION"
+```
+
 ## PostgreSQL Diagnostics Are Unavailable
 
 Symptoms:
@@ -182,6 +209,8 @@ Expected result when available:
 
 - The JSON payload includes `postgres.contractVersion`.
 - The diagnostics object includes `schemaVersion`.
+- The optional `sections` array groups PostgreSQL warnings under the
+  `postgresql` section while preserving the flat `warnings` array.
 - Missing or malformed metric rows are reported as unavailable diagnostics
   instead of being treated as success.
 
@@ -222,4 +251,3 @@ WPMOO_ENV=stage WPMOO_ALLOW_DESTRUCTIVE=1 WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1 ./moo
 Use the guard flag only when the command is intentional, reviewed, and has an
 appropriate rollback path. Migration-risk lifecycle commands may also require
 `WPMOO_ALLOW_MIGRATIONS=1`.
-

package/package.json

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