@wpmoo/odoo 0.8.60 → 0.8.62

package/README.md

@@ -139,10 +139,12 @@ npx @wpmoo/odoo --version
 
 npx @wpmoo/odoo status
 npx @wpmoo/odoo doctor
+npx @wpmoo/odoo doctor --fix
 npx @wpmoo/odoo add-repo --repo-url https://github.com/example-org/odoo_sample_module_reports.git
 npx @wpmoo/odoo remove-repo --repo odoo_sample_module_reports
 npx @wpmoo/odoo add-module --repo odoo_sample_module --module odoo_sample_module_base
 npx @wpmoo/odoo remove-module --repo odoo_sample_module --module odoo_sample_module_base
+npx @wpmoo/odoo reset --dry-run
 npx @wpmoo/odoo reset
 
 npx @wpmoo/odoo start
@@ -160,6 +162,7 @@ npx @wpmoo/odoo pot sale devel i18n/sale.pot
 
 npx @wpmoo/odoo resetdb devel sale
 npx @wpmoo/odoo snapshot devel before-update
+npx @wpmoo/odoo restore-snapshot --dry-run before-update devel
 npx @wpmoo/odoo restore-snapshot before-update devel
 ```
 
@@ -227,10 +230,17 @@ cp .env.example .env
 ./moo pot sale devel i18n/sale.pot
 
 ./moo snapshot devel before-update
+./moo restore-snapshot --dry-run before-update devel
 ./moo restore-snapshot before-update devel
 ./moo resetdb devel sale
 ```
 
+`restore-snapshot --dry-run` validates the selected snapshot and prints the
+restore plan without changing the database or filestore. Generated environments
+also support `WPMOO_SNAPSHOT_RETENTION_COUNT` for pruning old snapshot files.
+When `WPMOO_ENV=stage` or `WPMOO_ENV=prod`, destructive database actions such
+as `resetdb` and real `restore-snapshot` require `WPMOO_ALLOW_DESTRUCTIVE=1`.
+
 Use `npx @wpmoo/odoo ...` for package/operator commands such as `create`, `add-repo`, `remove-repo`, `add-module`, `remove-module`, `status`, `doctor`, and `reset`. Use `./moo ...` inside a generated environment for local daily Compose commands.
 
 ## Repository and Module Management
@@ -346,9 +356,15 @@ Docker Compose access, GitHub CLI authentication when available, and PostgreSQL
 18 compatibility in compose mount targets (for mounts to
 `/var/lib/postgresql/data` or `/var/lib/postgresql/18/docker`).
 
+Use `doctor --fix` for safe file-level repairs. It can normalize PostgreSQL 18
+mount targets and regenerate `odoo/custom/manifests/sources.yaml` from
+metadata plus `.gitmodules`, then it runs doctor again and reports any remaining
+manual issues.
+
 Safe reset refreshes generated environment files without deleting product source code:
 
 ```bash
+npx @wpmoo/odoo reset --dry-run
 npx @wpmoo/odoo reset
 ```
 
@@ -357,6 +373,9 @@ Safe reset updates generated files such as `.wpmoo/odoo.json`, `moo`,
 Agent Skills. Compose overlays like `compose.yaml` and `compose/dev.yaml` are
 also refreshed from the current compose template source.
 
+Use `reset --dry-run` first when you want a deterministic preview of refreshed
+files and cleanup warnings without writing to the environment.
+
 It does not touch source repo folders under
 `odoo/custom/src/private`, module source code, Git history, remotes, or
 branches. It also preserves local runtime artifacts and custom source layout
@@ -373,8 +392,10 @@ Recommended recovery pattern:
 
 ```bash
 ./moo snapshot devel before-reset
+npx @wpmoo/odoo reset --dry-run
 npx @wpmoo/odoo reset
-npx @wpmoo/odoo doctor
+npx @wpmoo/odoo doctor --fix
+./moo restore-snapshot --dry-run before-reset devel
 ./moo restore-snapshot before-reset devel
 ```
 

package/dist/cli.js

@@ -464,11 +464,25 @@ function removeRepoOptionsFromArgs(argv) {
         stage: booleanOption(values, 'stage', true),
     };
 }
-function resetOptionsFromArgs(argv) {
+function resetCommandOptionsFromArgs(argv) {
     const { values } = parseArgs(argv);
     return {
         target: resolve(stringOption(values, 'target') ?? process.cwd()),
         stage: booleanOption(values, 'stage', true),
+        dryRun: booleanOption(values, 'dryRun', false),
+    };
+}
+function doctorOptionsFromArgs(argv) {
+    if (argv.length === 0) {
+        return {};
+    }
+    const { values } = parseArgs(argv);
+    const keys = Object.keys(values);
+    if (keys.length !== 1 || !Object.hasOwn(values, 'fix')) {
+        throw new Error('Usage: wpmoo doctor');
+    }
+    return {
+        fix: booleanOption(values, 'fix', false),
     };
 }
 function sourceUsage() {
@@ -859,17 +873,20 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
     }
     if (route.command === 'reset') {
         console.log(renderBanner());
-        const options = resetOptionsFromArgs(route.argv);
-        await safeResetEnvironment(options);
+        const options = resetCommandOptionsFromArgs(route.argv);
+        if (options.dryRun) {
+            console.log(renderSafeResetPreview(options.target, options.stage));
+            return;
+        }
+        const resetOptions = { target: options.target, stage: options.stage };
+        await safeResetEnvironment(resetOptions);
         outro(`Safe reset refreshed generated environment files in ${options.target}.`);
         return;
     }
     if (route.command === 'doctor') {
-        if (route.argv.length > 0) {
-            throw new Error('Usage: wpmoo doctor');
-        }
+        const options = doctorOptionsFromArgs(route.argv);
         console.log(renderBanner());
-        console.log(await runDoctor(cwd));
+        console.log(options.fix === undefined ? await runDoctor(cwd) : await runDoctor(cwd, options));
         return;
     }
     if (route.command === 'status') {

package/dist/daily-actions.js

@@ -62,7 +62,7 @@ function usage(command) {
     if (command === 'snapshot')
         return 'Usage: wpmoo snapshot [db] [snapshot-name]';
     if (command === 'restore-snapshot')
-        return 'Usage: wpmoo restore-snapshot <snapshot-name> [db]';
+        return 'Usage: wpmoo restore-snapshot [--dry-run] <snapshot-name> [db]';
     if (command === 'lint')
         return 'Usage: wpmoo lint';
     return 'Usage: wpmoo pot <module[,module]> [db] [output]';
@@ -89,6 +89,17 @@ function positionalArgs(command, argv, min, max) {
     }
     return argv;
 }
+function restoreSnapshotArgs(argv) {
+    const args = [...argv];
+    const dryRun = args[0] === '--dry-run';
+    if (dryRun) {
+        args.shift();
+    }
+    if (args.length < 1 || args.length > 2 || args.some((arg) => arg.startsWith('-'))) {
+        throw new Error(usage('restore-snapshot'));
+    }
+    return dryRun ? ['--dry-run', ...args] : args;
+}
 function testArgs(argv) {
     const [modules, ...rest] = argv;
     if (!modules || modules.startsWith('-'))
@@ -129,7 +140,7 @@ function scriptArgs(command, argv) {
     if (command === 'snapshot')
         return positionalArgs(command, argv, 0, 2);
     if (command === 'restore-snapshot')
-        return positionalArgs(command, argv, 1, 2);
+        return restoreSnapshotArgs(argv);
     if (command === 'lint')
         return ensureNoArgs(command, argv);
     return positionalArgs(command, argv, 1, 3);

package/dist/doctor.js

@@ -1,11 +1,11 @@
-import { access, readFile } from 'node:fs/promises';
+import { access, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { execa } from 'execa';
 import { detectComposeLayout, readEnvFile, selectedComposeEnvironment } from './compose-layout.js';
 import { dailyActionScripts } from './daily-actions.js';
 import { defaultPostgresVersion } from './external-templates.js';
-import { defaultOdooVersion, markerPath } from './environment.js';
-import { listGitmoduleSources, readSourceManifest, sourceManifestPath, } from './source-manifest.js';
+import { defaultOdooVersion, markerPath, replaceSourceRepos } from './environment.js';
+import { listGitmoduleSources, readSourceManifest, sourceReposFromManifest, sourceManifestPath, syncManifestFromMetadataAndGitmodules, writeSourceManifest, } from './source-manifest.js';
 const realCommandRunner = async (command, args, options) => {
     const result = await execa(command, args, { cwd: options.cwd });
     return { stdout: result.stdout, stderr: result.stderr };
@@ -37,6 +37,9 @@ function commandErrorText(error) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function isDoctorOptions(value) {
+    return isRecord(value);
+}
 const incompatiblePostgres18MountTargets = ['/var/lib/postgresql/data', '/var/lib/postgresql/18/docker'];
 function parsePostgresMajorFromValue(value) {
     if (!value)
@@ -63,6 +66,48 @@ function hasInvalidPostgres18Mount(line, mountTarget) {
     ];
     return shortPatterns.some((pattern) => pattern.test(line));
 }
+function isNonAmbiguousLineForMountFix(line, mountTarget) {
+    return hasInvalidPostgres18Mount(line, mountTarget);
+}
+function replaceMountTargetInLine(line, from, to) {
+    return line.split(from).join(to);
+}
+function normalizePostgres18MountTargetsInComposeContent(content) {
+    const fixedTargets = [];
+    const fixed = [];
+    const hasTrailingNewline = content.endsWith('\n');
+    const comparableContent = hasTrailingNewline ? content.slice(0, -1) : content;
+    const lines = comparableContent.split(/\r?\n/);
+    const nextLines = [];
+    for (const line of lines) {
+        const commentIndex = line.indexOf('#');
+        const comment = commentIndex === -1 ? '' : line.slice(commentIndex);
+        const body = commentIndex === -1 ? line : line.slice(0, commentIndex);
+        let nextBody = body;
+        let lineFixed = false;
+        for (const target of incompatiblePostgres18MountTargets) {
+            if (!isNonAmbiguousLineForMountFix(body, target))
+                continue;
+            nextBody = replaceMountTargetInLine(nextBody, target, '/var/lib/postgresql');
+            if (!fixedTargets.includes(target)) {
+                fixedTargets.push(target);
+            }
+            lineFixed = true;
+        }
+        if (lineFixed) {
+            fixed.push(line);
+            nextLines.push(`${nextBody}${comment}`);
+        }
+        else {
+            nextLines.push(line);
+        }
+    }
+    return {
+        content: `${nextLines.join('\n')}${hasTrailingNewline ? '\n' : ''}`,
+        fixed,
+        fixedTargets,
+    };
+}
 function invalidPostgres18MountTargetsInCompose(content) {
     const badTargets = new Set();
     for (const rawLine of content.split(/\r?\n/)) {
@@ -199,7 +244,7 @@ function formatKeyForPath(key) {
     const [sourceType, ...pathParts] = key.split(':');
     return sourceRepoPath(sourceType, pathParts.join(':'));
 }
-function checkSourceConsistency(sourceRepos, manifestEntries, gitmoduleSources, manifestExists) {
+function checkSourceConsistency(sourceRepos, manifestEntries, gitmoduleSources, manifestExists, gitmodulesExists) {
     if (!manifestExists) {
         return [];
     }
@@ -224,13 +269,21 @@ function checkSourceConsistency(sourceRepos, manifestEntries, gitmoduleSources,
         if (!metadataEntries.has(key)) {
             errors.push(`Manifest source entry missing in metadata: ${formatKeyForPath(key)}`);
         }
-        if (!gitmoduleSet.has(key)) {
+        if (gitmodulesExists && !gitmoduleSet.has(key)) {
             errors.push(`Manifest source path missing in .gitmodules: ${formatKeyForPath(key)}`);
         }
     }
     return errors;
 }
-export async function runDoctor(target = process.cwd(), runner = realCommandRunner) {
+async function repairSourceManifestFromDiscoveredState(target, sourceRepos, fallbackBranch, gitmoduleSources) {
+    const entries = syncManifestFromMetadataAndGitmodules(sourceRepos, fallbackBranch, gitmoduleSources);
+    await writeSourceManifest(target, entries);
+    await replaceSourceRepos(target, sourceReposFromManifest(entries));
+}
+export async function runDoctor(target = process.cwd(), runnerOrOptions = realCommandRunner, options = {}) {
+    const actualRunner = isDoctorOptions(runnerOrOptions) ? realCommandRunner : runnerOrOptions;
+    const actualOptions = isDoctorOptions(runnerOrOptions) ? runnerOrOptions : options;
+    const appliedFixes = [];
     const lines = ['WPMoo doctor'];
     const errors = [];
     const warnings = [];
@@ -272,6 +325,16 @@ export async function runDoctor(target = process.cwd(), runner = realCommandRunn
                     errors.push(`Cannot read compose file for compatibility check: ${file}: ${errorMessage(error)}`);
                     continue;
                 }
+                if (actualOptions.fix) {
+                    const normalization = normalizePostgres18MountTargetsInComposeContent(content);
+                    if (normalization.fixed.length > 0) {
+                        await writeFile(composePath, normalization.content, 'utf8');
+                        for (const target of normalization.fixedTargets) {
+                            appliedFixes.push(`Normalized PostgreSQL 18 mount target in '${file}': replaced '${target}' -> '/var/lib/postgresql'`);
+                        }
+                        continue;
+                    }
+                }
                 const badMounts = invalidPostgres18MountTargetsInCompose(content);
                 for (const badMount of badMounts) {
                     errors.push(`PostgreSQL 18 compatibility issue in '${file}': mount target '${badMount}' is invalid; recommend using '/var/lib/postgresql'`);
@@ -301,17 +364,43 @@ export async function runDoctor(target = process.cwd(), runner = realCommandRunn
     const manifestPath = join(target, sourceManifestPath);
     const hasManifest = await exists(manifestPath);
     let manifestEntries = [];
+    let manifestReadError;
     if (hasManifest) {
         try {
             manifestEntries = (await readSourceManifest(target)).sources;
         }
         catch (error) {
-            errors.push(`Failed to read source manifest ${sourceManifestPath}: ${errorMessage(error)}`);
+            manifestReadError = `Failed to read source manifest ${sourceManifestPath}: ${errorMessage(error)}`;
+            if (!actualOptions.fix) {
+                errors.push(manifestReadError);
+            }
         }
     }
     const gitmoduleSources = await listGitmoduleSources(target);
-    if (errors.length === 0 || manifestEntries.length > 0) {
-        errors.push(...checkSourceConsistency(sourceRepos, manifestEntries, gitmoduleSources, hasManifest));
+    const hasGitmodules = await exists(join(target, '.gitmodules'));
+    const sourceConsistencyIssues = !manifestReadError
+        ? checkSourceConsistency(sourceRepos, manifestEntries, gitmoduleSources, hasManifest, hasGitmodules)
+        : [];
+    const shouldSyncSources = actualOptions.fix &&
+        (manifestReadError || sourceConsistencyIssues.length > 0 || (!hasManifest && (sourceRepos.length > 0 || gitmoduleSources.length > 0)));
+    if (sourceConsistencyIssues.length > 0) {
+        if (actualOptions.fix) {
+            const uniqueIssues = [...new Set(sourceConsistencyIssues)];
+            appliedFixes.push(...uniqueIssues.map((issue) => `Will regenerate source manifest and metadata to fix: ${issue}`));
+        }
+        else {
+            errors.push(...sourceConsistencyIssues);
+        }
+    }
+    else if (manifestReadError) {
+        appliedFixes.push('Will regenerate source manifest and metadata after repairing source manifest read failure.');
+    }
+    else if (shouldSyncSources) {
+        appliedFixes.push('Will create missing source manifest from metadata and .gitmodules state.');
+    }
+    if (shouldSyncSources && actualOptions.fix) {
+        await repairSourceManifestFromDiscoveredState(target, sourceRepos, odooVersion, gitmoduleSources);
+        appliedFixes.push('Synced source manifest and metadata with current metadata/.gitmodules state.');
     }
     if (env) {
         const httpPort = validatePort('HTTP_PORT', env, errors);
@@ -324,14 +413,14 @@ export async function runDoctor(target = process.cwd(), runner = realCommandRunn
         }
     }
     try {
-        await runner('docker', ['version'], { cwd: target });
+        await actualRunner('docker', ['version'], { cwd: target });
         lines.push('OK docker CLI');
     }
     catch (error) {
         errors.push(`Docker CLI check failed: ${errorMessage(error)}`);
     }
     try {
-        await runner('docker', ['compose', 'version'], { cwd: target });
+        await actualRunner('docker', ['compose', 'version'], { cwd: target });
         lines.push('OK docker compose');
     }
     catch (error) {
@@ -339,7 +428,7 @@ export async function runDoctor(target = process.cwd(), runner = realCommandRunn
     }
     if (sourceRepos.length > 0) {
         try {
-            const result = await runner('git', ['submodule', 'status', '--recursive'], { cwd: target });
+            const result = await actualRunner('git', ['submodule', 'status', '--recursive'], { cwd: target });
             const submoduleErrors = sourceSubmoduleStatusErrors(result.stdout, sourceRepos);
             errors.push(...submoduleErrors);
             if (submoduleErrors.length === 0) {
@@ -356,16 +445,33 @@ export async function runDoctor(target = process.cwd(), runner = realCommandRunn
         }
     }
     try {
-        await runner('gh', ['auth', 'status'], { cwd: target });
+        await actualRunner('gh', ['auth', 'status'], { cwd: target });
         lines.push('OK GitHub CLI auth');
     }
     catch (error) {
         warnings.push(`WARN GitHub CLI auth: ${errorMessage(error)}`);
     }
     if (errors.length > 0) {
+        if (actualOptions.fix && appliedFixes.length > 0) {
+            return [
+                'Doctor auto-fixes were not enough to satisfy all checks.',
+                ...appliedFixes.map((fix) => `- ${fix}`),
+                renderFailure(errors),
+            ].join('\n');
+        }
         throw new Error(renderFailure(errors));
     }
     lines.push(...warnings);
     lines.push('Doctor checks passed.');
-    return lines.join('\n');
+    const report = lines.join('\n');
+    if (actualOptions.fix && appliedFixes.length > 0) {
+        const postFixReport = await runDoctor(target, actualRunner, { ...actualOptions, fix: false });
+        return [
+            'Applied safe doctor fixes:',
+            ...appliedFixes.map((fix) => `- ${fix}`),
+            '',
+            postFixReport,
+        ].join('\n');
+    }
+    return report;
 }

package/dist/external-templates.js

@@ -37,6 +37,12 @@ export function renderComposeEnvExample(options) {
         'POSTGRES_PASSWORD=odoo',
         'ODOO_MASTER_PASSWORD=admin',
         `ODOO_TEST_MODULE=${defaultTestModule(options)}`,
+        'WPMOO_ENV=dev',
+        'WPMOO_SNAPSHOT_RETENTION_COUNT=0',
+        '',
+        '# Required only when intentionally running destructive database actions',
+        '# such as resetdb or restore-snapshot with WPMOO_ENV=stage or WPMOO_ENV=prod.',
+        '# WPMOO_ALLOW_DESTRUCTIVE=1',
         '',
     ].join('\n');
 }

package/dist/help.js

@@ -15,8 +15,8 @@ Usage:
   npx @wpmoo/odoo source remove --repo <name> [--source-type private|oca|external]
   npx @wpmoo/odoo add-module --repo <source-repo> --module <module-name>
   npx @wpmoo/odoo remove-module --repo <source-repo> --module <module-name>
-  npx @wpmoo/odoo reset
-  npx @wpmoo/odoo doctor
+  npx @wpmoo/odoo reset [--dry-run]
+  npx @wpmoo/odoo doctor [--fix]
   npx @wpmoo/odoo start
   npx @wpmoo/odoo stop
   npx @wpmoo/odoo logs [service]
@@ -28,7 +28,7 @@ Usage:
   npx @wpmoo/odoo test <module[,module]> [--db <db>] [--mode init|update] [--tags <tags>]
   npx @wpmoo/odoo resetdb [db] [module[,module]]
   npx @wpmoo/odoo snapshot [db] [snapshot-name]
-  npx @wpmoo/odoo restore-snapshot <snapshot-name> [db]
+  npx @wpmoo/odoo restore-snapshot [--dry-run] <snapshot-name> [db]
   npx @wpmoo/odoo lint
   npx @wpmoo/odoo pot <module[,module]> [db] [output]
 
@@ -87,6 +87,7 @@ Wizard local-only path:
 Status and doctor:
   status: fast and offline. Reads local environment metadata and files only.
   doctor: deeper health check. May check Docker CLI access and GitHub workflows.
+  doctor --fix: applies safe file-level repairs. Runs doctor again after fixes.
 
 Task recipes:
   Create environment:
@@ -105,11 +106,14 @@ Task recipes:
     npx @wpmoo/odoo test <module[,module]> [--db <db>] [--mode init|update] [--tags <tags>]
   Safe reset and recover:
     npx @wpmoo/odoo snapshot [db] [snapshot-name]
+    npx @wpmoo/odoo reset --dry-run
     npx @wpmoo/odoo reset
+    npx @wpmoo/odoo restore-snapshot --dry-run <snapshot-name> [db]
     npx @wpmoo/odoo restore-snapshot <snapshot-name> [db]
   Daily command checks:
     npx @wpmoo/odoo status
     npx @wpmoo/odoo doctor
+    npx @wpmoo/odoo doctor --fix
     npx @wpmoo/odoo logs [service]
     npx @wpmoo/odoo restart
 

package/dist/templates.js

@@ -243,6 +243,7 @@ cp .env.example .env
 
 \`\`\`bash
 ./moo snapshot devel before-update
+./moo restore-snapshot --dry-run before-update devel
 ./moo restore-snapshot before-update devel
 \`\`\`
 
@@ -371,7 +372,7 @@ usage() {
     "test") echo "Usage: ./moo test <module[,module]> [--db <db>] [--mode init|update] [--tags <tags>]" ;;
     "resetdb") echo "Usage: ./moo resetdb [db] [module[,module]]" ;;
     "snapshot") echo "Usage: ./moo snapshot [db] [snapshot-name]" ;;
-    "restore-snapshot") echo "Usage: ./moo restore-snapshot <snapshot-name> [db]" ;;
+    "restore-snapshot") echo "Usage: ./moo restore-snapshot [--dry-run] <snapshot-name> [db]" ;;
     "lint") echo "Usage: ./moo lint" ;;
     "pot") echo "Usage: ./moo pot <module[,module]> [db] [output]" ;;
   esac
@@ -526,8 +527,14 @@ case "$command" in
     ;;
   "restore-snapshot")
     shift
+    restore_args=()
+    if [[ "\${1:-}" == "--dry-run" ]]; then
+      restore_args+=("--dry-run")
+      shift
+    fi
     positional_args "$command" 1 2 "$@"
-    run_script ./scripts/restore-snapshot.sh "$@"
+    restore_args+=("$@")
+    run_script ./scripts/restore-snapshot.sh "\${restore_args[@]}"
     ;;
   "lint")
     shift
@@ -692,7 +699,7 @@ Useful maintenance commands:
 ./moo lint
 ./moo resetdb [db] [module[,module]]
 ./moo snapshot [db] [snapshot-name]
-./moo restore-snapshot <snapshot-name> [db]
+./moo restore-snapshot [--dry-run] <snapshot-name> [db]
 ./moo pot <module[,module]> [db] [output]
 \`\`\`
 

package/docs/generated-environment-verification.md

@@ -21,12 +21,13 @@ not validate staging or production deployments.
 | Compose resource files | Compact compose layout is present (`compose.yaml` + environment overlays under `compose/`), plus config/resources/scripts. | `npx @wpmoo/odoo create ...` |
 | `./moo` delegation | `./moo` dispatches fixed daily actions to the matching script and preserves argument pass-through. | `./moo <action> ...` |
 | Doctor checks | Metadata, compose files, scripts, source repo paths, and local tooling checks behave as expected. | `npx @wpmoo/odoo doctor` or `./moo doctor` |
-| Generated Postgres checks | For PostgreSQL 18 environments, doctor validates db mount targets avoid old PG image-specific paths. | `npx @wpmoo/odoo 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/odoo 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/odoo doctor`, `npx @wpmoo/odoo doctor --fix` |
 | Source repo add/remove | Source repository registration and submodule lifecycle behave correctly. | `npx @wpmoo/odoo add-repo ...`, `npx @wpmoo/odoo remove-repo ...` |
 | Source manifest sync | Source repo metadata, `.gitmodules`, and `odoo/custom/manifests/sources.yaml` stay aligned. | `npx @wpmoo/odoo source list`, `npx @wpmoo/odoo source sync` |
 | Module add/remove | Module registration changes are applied to the selected source repo config. | `npx @wpmoo/odoo add-module ...`, `npx @wpmoo/odoo remove-module ...` |
-| Safe reset | Generated files are refreshed (including `compose.yaml` overlays and env example) without deleting source module code. Local runtime/data directories and custom source layout content are preserved; legacy user-editable paths from older templates may remain and are reported for manual cleanup. | `npx @wpmoo/odoo reset` |
-| Snapshot/restore and lint/pot | These actions are delegated by `./moo` to compose scripts without extra package-side logic. | `./moo snapshot ...`, `./moo restore-snapshot ...`, `./moo lint`, `./moo pot ...` |
+| Safe reset | Generated files are refreshed (including `compose.yaml` overlays and env example) without deleting source module code. Local runtime/data directories and custom source layout content are preserved; legacy user-editable paths from older templates may remain and are reported for manual cleanup. | `npx @wpmoo/odoo reset --dry-run`, `npx @wpmoo/odoo reset` |
+| Snapshot/restore and lint/pot | These actions are delegated by `./moo` to compose scripts. Restore preview, snapshot retention, and stage/prod destructive guards are preserved by the package argument layer. | `./moo snapshot ...`, `./moo restore-snapshot --dry-run ...`, `./moo restore-snapshot ...`, `./moo lint`, `./moo pot ...` |
 
 ## Compact compose checks
 
@@ -45,6 +46,10 @@ Default local development uses `compose.yaml` plus `compose/dev.yaml`.
 `WPMOO_ENV=stage` or `WPMOO_ENV=prod` must only be used after production-grade
 secrets and volumes are configured.
 
+When `WPMOO_ENV=stage` or `WPMOO_ENV=prod`, generated compose scripts refuse
+destructive database actions such as `resetdb` and real `restore-snapshot`
+unless `.env` explicitly sets `WPMOO_ALLOW_DESTRUCTIVE=1`.
+
 For PostgreSQL 18 environments (including `POSTGRES_IMAGE=postgres:18`), ensure db
 volume and tmpfs mount targets use `/var/lib/postgresql` directly:
 
@@ -56,6 +61,10 @@ volume and tmpfs mount targets use `/var/lib/postgresql` directly:
 Paths such as `/var/lib/postgresql/data` and `/var/lib/postgresql/18/docker` are
 no longer accepted by the package `doctor` check.
 
+`doctor --fix` may rewrite these safe mount targets to `/var/lib/postgresql`.
+It does not upgrade existing database data; if a real PostgreSQL major upgrade
+is involved, use PostgreSQL upgrade tooling first.
+
 ## Safe reset policy
 
 Safe reset intentionally avoids deleting user-editable legacy paths from old
@@ -80,6 +89,21 @@ odoo/custom/patches/
 odoo/custom/manifests/
 ```
 
+Run `npx @wpmoo/odoo reset --dry-run` before writing changes when you need to
+review the generated file refresh plan.
+
+## Snapshot policy
+
+Use restore preview before a destructive restore:
+
+```bash
+./moo restore-snapshot --dry-run <snapshot-name> [db]
+```
+
+`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.
+
 ## Source manifest checks
 
 Generated environments include `odoo/custom/manifests/sources.yaml`. The manifest
@@ -99,8 +123,10 @@ manifest and normalize `.wpmoo/odoo.json` source entries:
 npx @wpmoo/odoo source sync
 ```
 
-`doctor` fails when manifest entries, metadata entries, and source submodule
-paths diverge.
+`doctor` fails when manifest entries, metadata entries, and registered source
+submodule paths diverge. `doctor --fix` can regenerate
+`odoo/custom/manifests/sources.yaml` from metadata plus `.gitmodules` when the
+manifest is missing, unreadable, or stale.
 
 ## Local verification commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpmoo/odoo",
-  "version": "0.8.60",
+  "version": "0.8.62",
   "description": "WPMoo Odoo lifecycle tooling for development, staging, and production workflows.",
   "type": "module",
   "repository": {