@wpmoo/toolkit 0.9.28 → 0.9.30

package/docs/1-0-readiness.md

@@ -11,13 +11,11 @@ Ready:
 - Generated environments use local `./moo` for daily commands.
 - Direct commands cover create, status, doctor, source, repository, module,
   service, database, snapshot, restore, lint, and POT workflows.
-- Deprecated package aliases remain compatibility paths:
+- Compatibility aliases remain available through the 1.x line:
   `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev`.
-
-Remaining decision:
-
-- Whether the optional unscoped `npx wpmoo` short alias should be promoted,
-  kept best-effort, or removed from public examples before `1.0.0`.
+- The optional unscoped `npx wpmoo` short alias remains best-effort and
+  warning-only. User-facing examples may mention it as optional, but
+  documentation, scripts, and automation should use `npx @wpmoo/toolkit`.
 
 ## Stable JSON Contracts
 
@@ -29,11 +27,10 @@ Ready:
 - `doctor --json --postgres` exposes a versioned `postgres` payload with
   `contractVersion` and diagnostics `schemaVersion`.
 - PostgreSQL diagnostics treat unavailable optional metrics as optional fields.
-
-Remaining decision:
-
-- Document a compatibility policy for future JSON schema changes, including
-  whether minor additive fields are allowed without a major release.
+- Post-1.0 JSON contracts allow additive optional fields in minor and patch
+  releases.
+- Automation should ignore unknown JSON fields.
+- Breaking JSON changes require a major release or a schemaVersion bump.
 
 ## Deprecated Alias Policy
 
@@ -44,11 +41,9 @@ Ready:
   releases.
 - The optional `wpmoo` short alias is warning-only and does not determine
   release validity.
-
-Remaining decision:
-
-- Set an explicit deprecation horizon for compatibility aliases after `1.0.0`,
-  or commit to maintaining them indefinitely.
+- Compatibility aliases remain available through the 1.x line.
+- Removing a compatibility alias requires a future major release and prior
+  notice.
 
 ## Generated File Compatibility
 
@@ -61,11 +56,10 @@ Ready:
 - PostgreSQL 18 mount compatibility is documented and doctor can apply safe
   mount-target fixes.
 - Generated `./moo` delegates daily commands and keeps local guard behavior.
-
-Remaining decision:
-
-- Define a generated-file migration policy for environments created by older
-  pre-1.0 releases.
+- Generated environments created by pre-1.0 releases are supported through safe
+  reset and doctor-guided generated-file migration checks.
+- Generated-file migration support must preserve product source repositories,
+  `.env` files, database dumps, and Docker volumes.
 
 ## Stage And Production Policy
 
@@ -79,11 +73,9 @@ Ready:
 - `restore-snapshot --dry-run`, `doctor`, and `doctor --postgres` remain safe
   preview/read-only paths.
 - Migration-risk lifecycle commands can require `WPMOO_ALLOW_MIGRATIONS=1`.
-
-Remaining decision:
-
-- Decide whether stage/prod approvals should gain a timestamped confirmation
-  file or continue to rely on environment variables only.
+- Environment-variable approvals remain supported through 1.x.
+- `.wpmoo/approvals.jsonl` adds time-bounded local approvals as an additive
+  safety layer, not as a replacement for env flags in 1.x.
 
 ## Release Artifact Policy
 
@@ -97,33 +89,59 @@ Ready:
   the current version already exists.
 - `npm run smoke:published -- "$VERSION"` is the preferred published package
   smoke check.
-
-Remaining decision:
-
-- Decide whether release smoke should include a generated-environment acceptance
-  run by default for `1.0.0` tags.
+- Generated-environment acceptance smoke is mandatory for a 1.0.0 release
+  candidate.
 
 ## Current Audit
 
-Last updated: 2026-05-21.
+Last updated: 2026-05-22.
 
 Completed checks:
 
-- Full local gate for Train 8 passed on 2026-05-21:
+- Full local gate through Train 19 passed on 2026-05-22:
   `npm run typecheck`, `npm test`, `npm run build`, and `git diff --check`.
-- Coverage passed on 2026-05-21: 72 test files, 682 tests, 92.32%
-  statements, 87.56% branches, 96.74% functions, and 92.32% lines.
-- Published CLI smoke passed against `@wpmoo/toolkit@0.9.27` with `npm exec`
-  for `wpmoo --version`, `wpmoo --help`, and `wpmoo doctor --help`.
+- Coverage passed on 2026-05-22: 75 test files, 722 tests, 92.00%
+  statements, 87.59% branches, 96.30% functions, and 92.00% lines.
+- Local release packaging passed for the 1.0 release-candidate surface with
+  `npm --cache /private/tmp/wpmoo-npm-cache pack --dry-run`; the package
+  contained 70 files and the expected `dist`, `docs/assets`, `docs/*.md`,
+  `README.md`, `LICENSE`, and `package.json` entries.
+- Local dist CLI smoke passed for `node dist/cli.js --version`, `--help`,
+  `create --help`, `doctor --help`, and `status --help`.
+- The generated-environment acceptance flow remains covered by
+  `test/smoke-published-script.test.ts`, including create, source list/sync,
+  safe reset preview, `doctor --fix`, snapshot, and restore dry-run steps.
 - Placeholder review found no `TODO`, `FIXME`, `TBD`, or `coming soon`
   markers in `README.md`, `docs`, or `src`.
 - Local markdown link review passed across `README.md` and `docs/*.md`.
-
-Final gap list:
-
-- Define JSON compatibility rules for post-1.0 additive fields.
-- Decide the long-term compatibility alias policy.
-- Decide generated-environment migration support for older pre-1.0 outputs.
-- Decide whether stage/prod approvals need timestamped confirmation files.
-- Decide whether generated-environment published smoke should be mandatory for
-  `1.0.0` tags.
+- Published CLI smoke previously passed against `@wpmoo/toolkit@0.9.27` with
+  `npm exec` for `wpmoo --version`, `wpmoo --help`, and
+  `wpmoo doctor --help`.
+
+Release-candidate notes:
+
+- Local `npm exec --package file:...` smoke against the generated tarball did
+  not complete in this restricted environment because package installation and
+  dependency resolution timed out before the CLI could run. This is not treated
+  as a product regression, but it prevents treating the current line as final
+  `1.0.0` evidence before a registry-backed smoke completes.
+- The next patch release should be published as `0.9.30`. Do not tag `1.0.0`
+  until `WPMOO_SMOKE_ENVIRONMENT=1 npm run smoke:published -- "$VERSION"`
+  passes against a registry-resolved package.
+- After a registry-backed generated-environment smoke passes, the remaining
+  1.0 decision is procedural: bump to `1.0.0`, rerun the full gate, rerun
+  `npm run release:check`, tag, and verify the required scoped artifacts.
+
+Final policy decisions:
+
+- JSON compatibility permits additive optional fields in minor and patch
+  releases; breaking changes require a major release or schemaVersion bump.
+- Compatibility aliases remain available through the 1.x line; removal requires
+  a future major release and prior notice.
+- Pre-1.0 generated environments are supported through safe reset and
+  doctor-guided generated-file migration checks that preserve source code and
+  local runtime data.
+- Environment-variable approvals remain supported through 1.x;
+  `.wpmoo/approvals.jsonl` is additive and local-only.
+- Generated-environment acceptance smoke is mandatory for a `1.0.0` release
+  candidate.

package/docs/command-reference.md

@@ -3,7 +3,11 @@
 Use `npx @wpmoo/toolkit ...` for package/operator commands. Use `./moo ...`
 inside a generated environment for daily local commands. The deprecated
 compatibility aliases `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev` redirect to
-the toolkit package; new automation should use `@wpmoo/toolkit`.
+the toolkit package; new automation should use `@wpmoo/toolkit`. Deprecated
+compatibility aliases remain available through the 1.x line. Removing a
+compatibility alias requires a future major release and prior notice. The
+unscoped `npx wpmoo` short alias is optional and best-effort; scripts should use
+`npx @wpmoo/toolkit`.
 
 ## Package Commands
 
@@ -38,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. |
@@ -65,6 +69,10 @@ Current JSON contract notes:
 - `doctor --json --postgres` adds `postgres.contractVersion` and a PostgreSQL
   diagnostics object with its own `schemaVersion`.
 - PostgreSQL fields are optional when a metric is unavailable.
+- 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
+  major release or a `schemaVersion` bump.
 
 ## Environment Variables
 
@@ -80,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`.
@@ -107,4 +133,3 @@ Prefer read-only and dry-run commands first:
 ./moo doctor --postgres
 ./moo restore-snapshot --dry-run before-change devel
 ```
-

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,7 +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 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.28",
+  "version": "0.9.30",
   "description": "WPMoo Toolkit for development, staging, and production lifecycle workflows.",
   "type": "module",
   "repository": {