@wpmoo/toolkit 0.9.26 → 0.9.28

package/docs/1-0-readiness.md

@@ -0,0 +1,129 @@
+# 1.0 Readiness
+
+This checklist tracks what must stay stable before WPMoo Toolkit can be
+released as `1.0.0`.
+
+## Stable Command Names
+
+Ready:
+
+- `npx @wpmoo/toolkit` is the official package entrypoint.
+- 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:
+  `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`.
+
+## Stable JSON Contracts
+
+Ready:
+
+- `status --json` uses `schemaVersion: 1`.
+- `source list --json` and `source sync --json` use `schemaVersion: 1`.
+- `doctor --json` uses `schemaVersion: 1`.
+- `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.
+
+## Deprecated Alias Policy
+
+Ready:
+
+- `@wpmoo/toolkit` is the supported package.
+- `@wpmoo/odoo` and `@wpmoo/odoo-dev` are required compatibility artifacts in
+  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.
+
+## Generated File Compatibility
+
+Ready:
+
+- Generated environments keep product source repositories under
+  `odoo/custom/src/private`, `odoo/custom/src/oca`, and
+  `odoo/custom/src/external`.
+- `safe reset` refreshes generated files while preserving source repositories.
+- 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.
+
+## Stage And Production Policy
+
+Ready:
+
+- Stage `install` and `update` require `WPMOO_ALLOW_STAGE_LIFECYCLE=1`.
+- Production `install`, `update`, and `test` require
+  `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
+- Destructive database commands require `WPMOO_ALLOW_DESTRUCTIVE=1` in stage
+  and production.
+- `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.
+
+## Release Artifact Policy
+
+Ready:
+
+- Required release artifacts are `@wpmoo/toolkit`, `@wpmoo/odoo`, and
+  `@wpmoo/odoo-dev`.
+- Publishing is handled by GitHub Actions Trusted Publishing after a `v<version>`
+  tag is pushed.
+- `npm run release:check` verifies package state and bumps patch versions when
+  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.
+
+## Current Audit
+
+Last updated: 2026-05-21.
+
+Completed checks:
+
+- Full local gate for Train 8 passed on 2026-05-21:
+  `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`.
+- 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.

package/docs/command-reference.md

@@ -0,0 +1,110 @@
+# Command Reference
+
+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`.
+
+## Package Commands
+
+| Command | Cockpit Equivalent | JSON | Notes |
+| --- | --- | --- | --- |
+| `npx @wpmoo/toolkit` | Open cockpit or create wizard | No | Opens the create wizard outside an environment and the cockpit inside one. |
+| `npx @wpmoo/toolkit create ...` | Create wizard | No | Creates a generated environment. Use `--target <path>` for a custom folder. |
+| `npx @wpmoo/toolkit status` | Diagnostics -> Environment status | Yes, `--json` | Fast local metadata and file check. |
+| `npx @wpmoo/toolkit doctor [--fix] [--postgres]` | Diagnostics -> Run doctor | Yes, `--json` | Deeper health checks. `--postgres` is read-only and advisory. |
+| `npx @wpmoo/toolkit source list` | Repositories | Yes, `--json` | Lists known source repositories. |
+| `npx @wpmoo/toolkit source sync` | Repositories | Yes, `--json` | Refreshes source manifest data. |
+| `npx @wpmoo/toolkit add-repo --repo-url <url>` | Repositories -> Add source repo | No | Adds a source repository category entry. |
+| `npx @wpmoo/toolkit remove-repo --repo <name>` | Repositories -> Remove source repo | No | Removes a source repository from the environment. |
+| `npx @wpmoo/toolkit add-module --repo <repo> --module <name>` | Modules -> Add module | No | Creates an Odoo module skeleton in a source repository. |
+| `npx @wpmoo/toolkit remove-module --repo <repo> --module <name>` | Modules -> Remove module | No | Removes module metadata; pass `--delete-files` to delete module files after dirty checks. |
+| `npx @wpmoo/toolkit reset [--dry-run]` | Maintenance -> Safe reset environment | No | Refreshes generated files while preserving source repositories. |
+
+## Generated Environment Commands
+
+Run these from the generated environment root:
+
+| Command | Cockpit Equivalent | Guarded In Stage/Prod | Notes |
+| --- | --- | --- | --- |
+| `./moo start` | Services -> Start services | No | Starts local Odoo services. Disabled in cockpit when already running. |
+| `./moo stop` | Services -> Stop services | No | Stops local services. Disabled in cockpit when services are stopped. |
+| `./moo restart` | Services -> Restart services | No | Restarts services. |
+| `./moo logs [service] [tail-lines]` | Services -> View logs | No | Streams or tails service logs. |
+| `./moo shell` | Services -> Open shell | No | Opens a shell in the Odoo service container. |
+| `./moo psql [db]` | Database -> Open psql | No | Opens a PostgreSQL prompt. |
+| `./moo install <module[,module]> [db]` | Modules -> Install module | Yes | Installs one or more modules. |
+| `./moo update <module[,module]> [db]` | Modules -> Update module | Yes | Updates one or more modules. |
+| `./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 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. |
+| `./moo doctor [--fix] [--postgres]` | Diagnostics -> Run doctor | No | Local health checks. |
+| `./moo status` | Diagnostics -> Environment status | No | Local environment status. |
+
+## JSON Output
+
+Machine-readable output is available for automation:
+
+```bash
+npx @wpmoo/toolkit status --json
+npx @wpmoo/toolkit source list --json
+npx @wpmoo/toolkit source sync --json
+npx @wpmoo/toolkit doctor --json
+npx @wpmoo/toolkit doctor --json --postgres
+```
+
+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 --postgres` adds `postgres.contractVersion` and a PostgreSQL
+  diagnostics object with its own `schemaVersion`.
+- PostgreSQL fields are optional when a metric is unavailable.
+
+## Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `WPMOO_ENV=dev|stage|prod` | Selects environment safety policy. Missing value behaves like development for local workflows. |
+| `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Allows `install` and `update` in stage. |
+| `WPMOO_ALLOW_PROD_LIFECYCLE=1` | Allows `install`, `update`, and `test` in production. |
+| `WPMOO_ALLOW_DESTRUCTIVE=1` | Allows destructive database commands in stage/prod. |
+| `WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1` | Allows destructive commands without a recent snapshot when that extra guard applies. |
+| `WPMOO_ALLOW_MIGRATIONS=1` | Allows lifecycle commands when migration scripts are detected. |
+| `WPMOO_NODE_BIN`, `WPMOO_NPX_BIN`, `WPMOO_GIT_BIN` | Override binaries used by release smoke scripts. |
+
+Process environment values take precedence over `.env` values for safety flags.
+
+## Exit Behavior
+
+- Successful commands exit `0`.
+- Invalid arguments, missing environment metadata, refused guard checks, dirty
+  deletion, and failed subprocesses exit non-zero.
+- `--json` commands still use process exit codes; automation should check both
+  the exit status and the `ok` field when present.
+- Guard failures are intentional failures. Do not silence them unless the named
+  `WPMOO_ALLOW_*` flag has been reviewed.
+
+## Stage And Production Restrictions
+
+| Command Family | Stage | Production |
+| --- | --- | --- |
+| `install`, `update` | Requires `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Requires `WPMOO_ALLOW_PROD_LIFECYCLE=1` |
+| `test` | Allowed | Requires `WPMOO_ALLOW_PROD_LIFECYCLE=1` |
+| `resetdb`, real `restore-snapshot` | Requires `WPMOO_ALLOW_DESTRUCTIVE=1` | Requires `WPMOO_ALLOW_DESTRUCTIVE=1` |
+| `restore-snapshot --dry-run` | Allowed | Allowed |
+| Commands with detected migration scripts | May require `WPMOO_ALLOW_MIGRATIONS=1` | May require `WPMOO_ALLOW_MIGRATIONS=1` |
+
+Prefer read-only and dry-run commands first:
+
+```bash
+./moo doctor
+./moo doctor --postgres
+./moo restore-snapshot --dry-run before-change devel
+```
+

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, 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` |
+| PostgreSQL diagnostics | Optional read-only, advisory-only database health and performance diagnostics (no automatic tuning), covering active/idle-in-transaction sessions, table health signals, WAL/capacity context, unused-index hints, and slow-query readiness. JSON mode emits a versioned PostgreSQL contract with optional fields when a metric 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 ...` |
@@ -76,16 +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, 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.
+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.
+
+`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.
 
 ## Safe reset policy
 

package/docs/handoff.md

@@ -64,3 +64,14 @@ Current command standard:
 
 - Use `npx @wpmoo/toolkit ...` for package/operator commands.
 - Use generated environment `./moo ...` for local compose daily commands.
+
+1.0 readiness references:
+
+- [Command Reference](command-reference.md)
+- [Lifecycle Recipes](lifecycle-recipes.md)
+- [Troubleshooting](troubleshooting.md)
+- [1.0 Readiness](1-0-readiness.md)
+
+Before a `1.0.0` tag, review the readiness gap list and decide whether the next
+milestone is "ship 1.0" or "finish named gaps." Do not treat the gap list as an
+open-ended cleanup queue.

package/docs/lifecycle-recipes.md

@@ -0,0 +1,190 @@
+# Lifecycle Recipes
+
+These recipes show WPMoo Toolkit as a sequence of Dev, Stage, and Production
+workflows. Replace repository names, module names, and database names with your
+project values.
+
+## Local Development Setup
+
+Create a generated environment from a workspace directory:
+
+```bash
+npx @wpmoo/toolkit create \
+  --product odoo_sample_module \
+  --odoo-version 19.0 \
+  --target ./odoo_sample_module_dev \
+  --dev-repo-url https://github.com/example-org/odoo_sample_module_dev.git \
+  --source-repo-url https://github.com/example-org/odoo_sample_module.git
+```
+
+Enter the environment and start daily work:
+
+```bash
+cd odoo_sample_module_dev
+./moo start
+./moo status
+./moo doctor
+```
+
+Use the cockpit for interactive workflows:
+
+```bash
+./moo
+```
+
+## Add A Source Repository
+
+Add a private source repository:
+
+```bash
+npx @wpmoo/toolkit add-repo \
+  --repo-url https://github.com/example-org/odoo-addons.git \
+  --source-type private
+```
+
+Refresh the source manifest:
+
+```bash
+npx @wpmoo/toolkit source sync
+npx @wpmoo/toolkit source list
+```
+
+Use `--source-type oca` for OCA repositories and `--source-type external` for
+third-party repositories.
+
+## Add A Module
+
+Create a module skeleton:
+
+```bash
+npx @wpmoo/toolkit add-module \
+  --repo odoo-addons \
+  --module moo_test \
+  --source-type private
+```
+
+Verify the generated module:
+
+```bash
+./moo status
+./moo lint
+```
+
+Expected module files include `__manifest__.py`, model imports, security access
+CSV, views, menus, and a post-install TransactionCase smoke test.
+
+## Install And Update A Module
+
+Start services and install the module into the development database:
+
+```bash
+./moo start
+./moo install moo_test devel
+```
+
+After code changes, update the module:
+
+```bash
+./moo update moo_test devel
+```
+
+If the cockpit shows module actions as disabled, run:
+
+```bash
+./moo status
+npx @wpmoo/toolkit source list
+```
+
+Then add or sync source repositories until installable modules are detected.
+
+## Run Tests
+
+Run module tests in development:
+
+```bash
+./moo test moo_test --db devel
+```
+
+Use explicit test mode when needed:
+
+```bash
+./moo test moo_test --db devel --mode update --tags /moo_test
+```
+
+For production, test execution is guarded:
+
+```bash
+WPMOO_ENV=prod WPMOO_ALLOW_PROD_LIFECYCLE=1 ./moo test moo_test --db devel
+```
+
+## Snapshot And Restore
+
+Take a snapshot before risky changes:
+
+```bash
+./moo snapshot devel before-moo-test-update
+```
+
+Preview a restore:
+
+```bash
+./moo restore-snapshot --dry-run before-moo-test-update devel
+```
+
+Restore intentionally:
+
+```bash
+WPMOO_ENV=stage WPMOO_ALLOW_DESTRUCTIVE=1 ./moo restore-snapshot before-moo-test-update devel
+```
+
+When the no-recent-snapshot guard applies to a destructive command, either make
+a fresh snapshot or set `WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1` after review.
+
+## Stage Dry-Run Validation
+
+Use stage for preview-first validation:
+
+```bash
+WPMOO_ENV=stage ./moo doctor
+WPMOO_ENV=stage ./moo doctor --postgres
+WPMOO_ENV=stage ./moo restore-snapshot --dry-run before-moo-test-update devel
+```
+
+Run lifecycle commands only after review:
+
+```bash
+WPMOO_ENV=stage WPMOO_ALLOW_STAGE_LIFECYCLE=1 ./moo update moo_test devel
+```
+
+If migration scripts are detected, WPMoo may also require:
+
+```bash
+WPMOO_ENV=stage WPMOO_ALLOW_STAGE_LIFECYCLE=1 WPMOO_ALLOW_MIGRATIONS=1 ./moo update moo_test devel
+```
+
+## Production-Safe Preview
+
+Production workflows should start with read-only checks:
+
+```bash
+WPMOO_ENV=prod ./moo status
+WPMOO_ENV=prod ./moo doctor
+WPMOO_ENV=prod ./moo doctor --postgres
+WPMOO_ENV=prod ./moo restore-snapshot --dry-run before-change devel
+```
+
+Production lifecycle commands require explicit approval flags:
+
+```bash
+WPMOO_ENV=prod WPMOO_ALLOW_PROD_LIFECYCLE=1 ./moo update moo_test devel
+```
+
+Destructive production commands require a separate flag and a rollback plan:
+
+```bash
+WPMOO_ENV=prod WPMOO_ALLOW_DESTRUCTIVE=1 ./moo restore-snapshot before-change devel
+```
+
+Do not set production flags globally in a shell profile. Prefer one-command
+environment variable prefixes so intent is visible in shell history.
+