@wpmoo/toolkit 0.9.30 → 0.9.32

package/README.md

@@ -154,8 +154,8 @@ search so names, repositories, and source categories can be filtered quickly.
 ./moo restore-snapshot --dry-run before-update devel
 ```
 
-In `WPMOO_ENV=stage`, `install` and `update` require `WPMOO_ALLOW_STAGE_LIFECYCLE=1`.
-In `WPMOO_ENV=prod`, `install`, `update`, and `test` require `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
+In `WPMOO_ENV=stage`, `install`, `update`, `stop`, and `restart` require `WPMOO_ALLOW_STAGE_LIFECYCLE=1`.
+In `WPMOO_ENV=prod`, `install`, `update`, `test`, `stop`, and `restart` require `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
 `resetdb` and real `restore-snapshot` require `WPMOO_ALLOW_DESTRUCTIVE=1` in `stage` and `prod`.
 `restore-snapshot --dry-run` remains allowed for preview.
 For short-lived local approvals, add JSONL entries to `.wpmoo/approvals.jsonl`; generated `.gitignore` keeps that ledger out of Git.
@@ -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/cli-routes/source.js

@@ -4,7 +4,7 @@ import { commandOdooVersion } from '../environment-version.js';
 import { outroPrompt } from '../prompts/index.js';
 import { addModuleRepo, removeModuleRepo } from '../repo-actions.js';
 import { normalizeRepositoryUrl } from '../repo-url.js';
-import { listSources, renderSourceList, sourceListJson, sourceSyncJson, syncSources, } from '../source-actions.js';
+import { listSources, renderSourceList, renderSourceSyncPlan, sourceListJson, sourceSyncPlan, sourceSyncPlanJson, sourceSyncJson, syncSources, } from '../source-actions.js';
 import { renderBanner } from '../templates.js';
 import { booleanOption, jsonOption, optionalSourceTypeValue, printJson, sourceTypeValue, stringOption, } from './options.js';
 export function renderedSourceRepoPath(target, sourceType, repoPath) {
@@ -52,6 +52,7 @@ export function sourceSyncOptionsFromArgs(argv) {
         target: resolve(stringOption(values, 'target') ?? process.cwd()),
         stage: booleanOption(values, 'stage', true),
         json: jsonOption(values),
+        dryRun: booleanOption(values, 'dryRun', false),
     };
 }
 export function sourceListOptionsFromArgs(argv) {
@@ -79,6 +80,16 @@ export async function runSourceCommand(argv) {
     }
     if (subcommand === 'sync') {
         const options = sourceSyncOptionsFromArgs(subcommandArgv);
+        if (options.dryRun) {
+            const plan = await sourceSyncPlan(options.target);
+            if (options.json) {
+                printJson(sourceSyncPlanJson(plan));
+                return;
+            }
+            console.log(renderBanner());
+            console.log(renderSourceSyncPlan(plan));
+            return;
+        }
         const sources = await syncSources({ target: options.target, stage: options.stage });
         if (options.json) {
             printJson(sourceSyncJson(sources, options.target));

package/dist/cli.js

@@ -676,6 +676,7 @@ function removeModuleOptionsFromArgs(argv) {
         moduleName,
         sourceType: optionalSourceTypeValue(values),
         deleteFiles: booleanOption(values, 'deleteFiles', false),
+        dryRun: booleanOption(values, 'dryRun', false),
         stage: booleanOption(values, 'stage', true),
     };
 }
@@ -1419,14 +1420,14 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
         const options = removeModuleOptionsFromArgs(route.argv);
         if (options) {
             console.log(renderBanner());
-            await removeModuleFromSourceRepo(options);
-            outroPrompt(`Removed module ${options.moduleName} from source repo ${options.repoPath}.`);
+            const report = await removeModuleFromSourceRepo(options);
+            outroPrompt(report.dryRun ? report.summary : `Removed module ${options.moduleName} from source repo ${options.repoPath}.`);
             return;
         }
         await showStartup(argv, skipUpdateCheck);
         const promptedOptions = await removeModuleOptionsFromPrompts();
-        await removeModuleFromSourceRepo(promptedOptions);
-        outroPrompt(`Removed module ${promptedOptions.moduleName} from source repo ${promptedOptions.repoPath}.`);
+        const report = await removeModuleFromSourceRepo(promptedOptions);
+        outroPrompt(report.dryRun ? report.summary : `Removed module ${promptedOptions.moduleName} from source repo ${promptedOptions.repoPath}.`);
         return;
     }
     if (route.command === 'reset') {
@@ -1451,6 +1452,9 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
             doctorOptions.postgres = options.postgres;
         }
         if (options.json) {
+            if (doctorOptions.fix) {
+                throw new Error('doctor --json --fix is not supported; run doctor --fix for human-readable auto-fix output, then doctor --json to inspect the post-fix state.');
+            }
             printJson(await getDoctorReport(cwd, doctorOptions));
             return;
         }

package/dist/cockpit/menu.js

@@ -20,7 +20,7 @@ const topLevelCategoryOrder = [
 ];
 const topLevelCommands = topLevelCategoryOrder.flatMap((category) => cockpitCommands.filter((command) => command.category === category && command.id !== 'exit'));
 const topLevelCommandLabelWidth = Math.max(...topLevelCommands.map((command) => command.label.length));
-const moduleDependentCommandIds = new Set(['list-modules', 'install', 'update', 'test', 'lint', 'pot', 'remove-module']);
+const moduleDependentCommandIds = new Set(['list-modules', 'install', 'update', 'test', 'pot', 'remove-module']);
 function rgb(red, green, blue, value) {
     return `\u001B[38;2;${red};${green};${blue}m${value}\u001B[39m`;
 }

package/dist/doctor.js

@@ -5,8 +5,9 @@ import { detectComposeLayout, readEnvFile, selectedComposeEnvironment } from './
 import { dailyActionScripts } from './daily-actions.js';
 import { defaultPostgresVersion } from './external-templates.js';
 import { defaultOdooVersion, markerPath, replaceSourceRepos } from './environment.js';
-import { POSTGRES_DIAGNOSTICS_CONTRACT_VERSION, POSTGRES_DIAGNOSTICS_QUERY, malformedPostgresDiagnosticKeys, missingPostgresDiagnosticKeys, parsePostgresDiagnostics, postgresPostgresWarnings, renderPostgresDiagnostics, structuredPostgresDiagnostics, unavailablePostgresDiagnosticsWarning, } from './postgres-diagnostics.js';
+import { POSTGRES_DIAGNOSTICS_CONTRACT_VERSION, POSTGRES_DIAGNOSTICS_OPTIONAL_QUERIES, POSTGRES_DIAGNOSTICS_QUERY, malformedPostgresDiagnosticKeys, missingPostgresDiagnosticKeys, parsePostgresDiagnostics, postgresPostgresWarnings, renderPostgresDiagnostics, structuredPostgresDiagnostics, unavailablePostgresDiagnosticsWarning, } from './postgres-diagnostics.js';
 import { listGitmoduleSources, readSourceManifest, sourceReposFromManifest, sourceManifestPath, syncManifestFromMetadataAndGitmodules, writeSourceManifest, } from './source-manifest.js';
+import { emptyModuleQualitySummary, mergeModuleQualitySummaries, scanModuleQuality, } from './module-quality.js';
 const realCommandRunner = async (command, args, options) => {
     const result = await execa(command, args, { cwd: options.cwd });
     return { stdout: result.stdout, stderr: result.stderr };
@@ -76,6 +77,13 @@ function isMetadataError(message) {
         message.startsWith('Invalid sourceRepos entry in .wpmoo/odoo.json'));
 }
 const incompatiblePostgres18MountTargets = ['/var/lib/postgresql/data', '/var/lib/postgresql/18/docker'];
+const defaultPostgresDiagnosticsTimeoutMs = 15_000;
+class PostgresDiagnosticsTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`PostgreSQL diagnostics timed out after ${timeoutMs}ms`);
+        this.name = 'PostgresDiagnosticsTimeoutError';
+    }
+}
 function parsePostgresMajorFromValue(value) {
     if (!value)
         return undefined;
@@ -86,16 +94,62 @@ function parsePostgresMajorFromValue(value) {
     const match = trimmed.match(/postgres:([0-9]{1,3})(?:[-._][A-Za-z0-9._-]+)?(?:@[\w:.-]+)?/i);
     return match?.[1];
 }
-async function readPostgresDiagnostics(target, runner) {
-    const queryLiteral = JSON.stringify(POSTGRES_DIAGNOSTICS_QUERY);
+async function withPostgresDiagnosticsTimeout(promise, timeoutMs) {
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new PostgresDiagnosticsTimeoutError(timeoutMs)), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
+function postgresDiagnosticsTimeoutMs(options) {
+    return typeof options.postgresTimeoutMs === 'number' &&
+        Number.isFinite(options.postgresTimeoutMs) &&
+        options.postgresTimeoutMs > 0
+        ? 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 = [
         `query=${queryLiteral}`,
         '. ./scripts/lib.sh >/dev/null',
         'compose exec -T db psql -X -q -t -A -U "${POSTGRES_USER:-odoo}" -d "${POSTGRES_DB:-postgres}" -c "$query"',
     ].join(' && ');
-    const result = await runner('bash', ['-lc', command], { cwd: target });
+    const result = await withPostgresDiagnosticsTimeout(runner('bash', ['-lc', command], { cwd: target }), timeoutMs);
     return parsePostgresDiagnostics(result.stdout);
 }
+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 (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, optionalProbeFailures };
+}
 function stripInlineComment(line) {
     const hashIndex = line.indexOf('#');
     if (hashIndex === -1)
@@ -254,10 +308,14 @@ const doctorSectionDefinitions = [
     { id: 'generated-files', title: 'Generated files' },
     { id: 'compose', title: 'Compose' },
     { id: 'source-repositories', title: 'Source repositories' },
+    { id: 'module-quality', title: 'Module quality' },
     { id: 'postgresql', title: 'PostgreSQL' },
     { id: 'host-tools', title: 'Host tools' },
 ];
 function doctorSectionForLine(line) {
+    if (line.startsWith('OK module quality') || line.startsWith('Module quality advisory:')) {
+        return 'module-quality';
+    }
     if (line.includes('PostgreSQL diagnostics') ||
         line.includes('PostgreSQL connection') ||
         line.includes('PostgreSQL slow-query') ||
@@ -521,6 +579,14 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
         errors.push(`Missing source repo path: ${relativePath}`);
     }
     checks.push(`OK source repos ${sourceRepos.length} checked`);
+    let moduleQuality = emptyModuleQualitySummary();
+    for (const repo of sourceRepos) {
+        const sourceType = normalizeSourceType(repo.sourceType);
+        const repoRoot = join(target, sourceRepoPath(sourceType, repo.path));
+        moduleQuality = mergeModuleQualitySummaries(moduleQuality, await scanModuleQuality(repoRoot, target));
+    }
+    checks.push(`OK module quality ${moduleQuality.totalModules} module${moduleQuality.totalModules === 1 ? '' : 's'} scanned`);
+    warnings.push(...moduleQuality.issues.map((issue) => `Module quality advisory: ${issue.path}: ${issue.issue}`));
     const manifestPath = join(target, sourceManifestPath);
     const hasManifest = await exists(manifestPath);
     let manifestEntries = [];
@@ -574,7 +640,7 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
     }
     if (actualOptions.postgres) {
         try {
-            const postgresDiagnostics = await readPostgresDiagnostics(target, actualRunner);
+            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) {
@@ -587,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));
             }
@@ -600,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/environment-policy.js

@@ -31,9 +31,9 @@ export const dailyActionPolicyTable = {
     stop: {
         isDestructive: () => false,
         isDryRunAllowed: false,
-        requiresStageLifecycleApproval: false,
-        requiresProdLifecycleApproval: false,
-        isAuditWorthy: () => false,
+        requiresStageLifecycleApproval: true,
+        requiresProdLifecycleApproval: true,
+        isAuditWorthy: () => true,
     },
     logs: {
         isDestructive: () => false,
@@ -45,9 +45,9 @@ export const dailyActionPolicyTable = {
     restart: {
         isDestructive: () => false,
         isDryRunAllowed: false,
-        requiresStageLifecycleApproval: false,
-        requiresProdLifecycleApproval: false,
-        isAuditWorthy: () => false,
+        requiresStageLifecycleApproval: true,
+        requiresProdLifecycleApproval: true,
+        isAuditWorthy: () => true,
     },
     shell: {
         isDestructive: () => false,

package/dist/external-templates.js

@@ -43,8 +43,14 @@ export function renderComposeEnvExample(options) {
         '# 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',
-        '# Required only when intentionally running install/update/test in WPMOO_ENV=prod.',
+        '# Required only when intentionally running install/update/stop/restart in WPMOO_ENV=stage.',
+        '# WPMOO_ALLOW_STAGE_LIFECYCLE=1',
+        '# Required only when intentionally running install/update/test/stop/restart in WPMOO_ENV=prod.',
         '# WPMOO_ALLOW_PROD_LIFECYCLE=1',
+        '# Required only when intentionally running a destructive stage/prod command without a recent snapshot.',
+        '# WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1',
+        '# Required only when intentionally running migration-risk lifecycle commands in stage/prod.',
+        '# WPMOO_ALLOW_MIGRATIONS=1',
         '',
     ].join('\n');
 }

package/dist/help.js

@@ -87,8 +87,8 @@ Daily actions:
   Use ./moo or npx @wpmoo/toolkit with the same daily action arguments.
 
 Lifecycle command guards:
-  In WPMOO_ENV=stage, install/update require WPMOO_ALLOW_STAGE_LIFECYCLE=1.
-  In WPMOO_ENV=prod, install/update/test require WPMOO_ALLOW_PROD_LIFECYCLE=1.
+  In WPMOO_ENV=stage, install/update/stop/restart require WPMOO_ALLOW_STAGE_LIFECYCLE=1.
+  In WPMOO_ENV=prod, install/update/test/stop/restart require WPMOO_ALLOW_PROD_LIFECYCLE=1.
   resetdb and real restore-snapshot require WPMOO_ALLOW_DESTRUCTIVE=1 in stage/prod.
   restore-snapshot --dry-run remains allowed for preview.
   Time-bounded local approvals may also be recorded in .wpmoo/approvals.jsonl.
@@ -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/dist/module-actions.js

@@ -253,8 +253,12 @@ async function moduleScaffoldChecks(target, sourceType, repoPath, moduleName, in
             id: 'tests',
             label: 'tests',
             ok: (await fileContains(join(destination, 'tests/__init__.py'), `from . import test_${moduleName}`)) &&
-                (await fileContains(join(destination, `tests/test_${moduleName}.py`), '')),
-            details: 'missing generated test file',
+                (await fileContains(join(destination, `tests/test_${moduleName}.py`), 'TransactionCase')) &&
+                (await fileContains(join(destination, `tests/test_${moduleName}.py`), '@tagged("post_install", "-at_install")')) &&
+                (await fileContains(join(destination, `tests/test_${moduleName}.py`), `class Test${moduleClassName(moduleName)}(TransactionCase):`)) &&
+                (await fileContains(join(destination, `tests/test_${moduleName}.py`), 'def test_create_record(self):')) &&
+                (await fileContains(join(destination, `tests/test_${moduleName}.py`), `self.env["${technicalName}"]`)),
+            details: 'missing generated TransactionCase test markers',
         },
     ];
     if (includeRegistration) {
@@ -375,23 +379,20 @@ async function assertModuleCleanBeforeDelete(target, sourceType, repoPath, modul
     const repoRoot = sourceRepoPath(target, sourceType, repoPath);
     try {
         const result = await git.run(repoRoot, ['status', '--short', '--', moduleName]);
-        if (result.stdout.trim() && (await moduleHasCommittedFiles(repoRoot, moduleName, git))) {
-            throw new Error(`Refusing to delete module ${moduleName} because it has dirty git changes in source repo ${repoPath}.`);
+        const status = result.stdout.trimEnd();
+        if (status.trim()) {
+            const hasUntrackedOrStaged = status
+                .split(/\r?\n/u)
+                .some((line) => line.startsWith('??') || /^[A-Z][A-Z ]\s/u.test(line));
+            const reason = hasUntrackedOrStaged ? 'uncommitted git changes' : 'dirty git changes';
+            throw new Error(`Refusing to delete module ${moduleName} because it has ${reason} in source repo ${repoPath}.`);
         }
     }
     catch (error) {
         if (error instanceof Error && error.message.startsWith('Refusing to delete module ')) {
             throw error;
         }
-    }
-}
-async function moduleHasCommittedFiles(repoRoot, moduleName, git) {
-    try {
-        const result = await git.run(repoRoot, ['ls-tree', '-r', '--name-only', 'HEAD', '--', moduleName]);
-        return Boolean(result.stdout.trim());
-    }
-    catch {
-        return false;
+        throw new Error(`Refusing to delete module ${moduleName} because git status could not be verified in source repo ${repoPath}.`);
     }
 }
 export async function addModuleToSourceRepo(options, git = realGit) {
@@ -483,6 +484,19 @@ export async function removeModuleFromSourceRepo(options, git = realGit) {
     const repoPath = validateRepoPath(options.repoPath);
     const moduleName = validateModuleName(options.moduleName);
     const sourceType = normalizeSourceType(options.sourceType);
+    const destination = modulePath(options.target, sourceType, repoPath, moduleName);
+    if (options.dryRun) {
+        return {
+            moduleName,
+            repoPath,
+            sourceType,
+            path: destination,
+            deleteFiles: options.deleteFiles,
+            dryRun: true,
+            ...(options.deleteFiles ? { wouldDeletePath: destination } : {}),
+            summary: `Previewed removal of module ${moduleName} from source repo ${repoPath}.`,
+        };
+    }
     if (options.deleteFiles) {
         await assertModuleCleanBeforeDelete(options.target, sourceType, repoPath, moduleName, git);
     }
@@ -492,7 +506,7 @@ export async function removeModuleFromSourceRepo(options, git = realGit) {
     }
     await updateModuleRegistration(options.target, sourceType, repoPath, moduleName, 'remove');
     if (options.deleteFiles) {
-        await rm(modulePath(options.target, sourceType, repoPath, moduleName), { recursive: true, force: true });
+        await rm(destination, { recursive: true, force: true });
     }
     if (options.stage) {
         if (options.deleteFiles) {
@@ -500,4 +514,14 @@ export async function removeModuleFromSourceRepo(options, git = realGit) {
         }
         await stageAll(git, options.target);
     }
+    return {
+        moduleName,
+        repoPath,
+        sourceType,
+        path: destination,
+        deleteFiles: options.deleteFiles,
+        dryRun: false,
+        ...(options.deleteFiles ? { wouldDeletePath: destination } : {}),
+        summary: `Removed module ${moduleName} from source repo ${repoPath}.`,
+    };
 }

package/dist/module-quality.js

@@ -154,6 +154,49 @@ function declaredModelIds(modelFileContents) {
     }
     return modelIds;
 }
+function declaredModelNames(modelFileContents) {
+    const modelNames = new Set();
+    for (const content of modelFileContents) {
+        for (const match of content.matchAll(/^\s*_name\s*=\s*["']([^"']+)["']/gmu)) {
+            const modelName = match[1]?.trim();
+            if (modelName) {
+                modelNames.add(modelName);
+            }
+        }
+        for (const match of content.matchAll(/^\s*_inherit\s*=\s*["']([^"']+)["']/gmu)) {
+            const modelName = match[1]?.trim();
+            if (modelName) {
+                modelNames.add(modelName);
+            }
+        }
+    }
+    return modelNames;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+function xmlRecordFieldValues(xmlFiles, recordModel, fieldName) {
+    const values = [];
+    const recordPattern = new RegExp(`<record\\b[^>]*\\bmodel=(["'])${escapeRegExp(recordModel)}\\1[^>]*>(.*?)</record>`, 'gsu');
+    const fieldPattern = new RegExp(`<field\\b[^>]*\\bname=(["'])${escapeRegExp(fieldName)}\\1[^>]*>(.*?)</field>`, 'gsu');
+    for (const content of xmlFiles) {
+        let recordMatch;
+        while ((recordMatch = recordPattern.exec(content))) {
+            const body = recordMatch[2] ?? '';
+            let fieldMatch;
+            while ((fieldMatch = fieldPattern.exec(body))) {
+                const value = fieldMatch[2]?.replace(/<[^>]+>/gu, '').trim();
+                if (value) {
+                    values.push(value);
+                }
+            }
+        }
+    }
+    return values;
+}
+function looksLikePlainModelName(value) {
+    return /^[a-zA-Z_][\w]*(?:\.[a-zA-Z_][\w]*)+$/u.test(value);
+}
 function accessCsvModelIds(content) {
     if (!content)
         return [];
@@ -206,6 +249,7 @@ export async function analyzeModuleDirectory(modulePath, moduleName = basename(m
     const modelFiles = await readPythonModelFiles(modulePath);
     const viewFiles = await readViewXmlFiles(modulePath);
     const viewXml = await Promise.all(viewFiles.map(async (fileName) => (await readOptionalFile(join(modulePath, 'views', fileName))) ?? ''));
+    const allViewXml = [...viewXml, ...menuXml];
     const depends = manifestDepends(manifest);
     const data = manifestData(manifest);
     const demo = manifestDemo(manifest);
@@ -241,6 +285,7 @@ export async function analyzeModuleDirectory(modulePath, moduleName = basename(m
     }
     const modelFileContents = await readModelFileContents(modulePath, modelFiles);
     const modelIds = declaredModelIds(modelFileContents);
+    const modelNames = declaredModelNames(modelFileContents);
     if (modelIds.size > 0) {
         for (const modelId of accessCsvModelIds(await readOptionalFile(join(modulePath, 'security/ir.model.access.csv')))) {
             if (!modelIds.has(modelId)) {
@@ -248,6 +293,18 @@ export async function analyzeModuleDirectory(modulePath, moduleName = basename(m
             }
         }
     }
+    if (modelNames.size > 0) {
+        for (const modelName of new Set(xmlRecordFieldValues(viewXml, 'ir.ui.view', 'model'))) {
+            if (looksLikePlainModelName(modelName) && !modelNames.has(modelName)) {
+                issues.push(moduleQualityIssue(moduleName, relativePath, `view XML references unknown model name: ${modelName}`, 'error'));
+            }
+        }
+        for (const modelName of new Set(xmlRecordFieldValues(allViewXml, 'ir.actions.act_window', 'res_model'))) {
+            if (looksLikePlainModelName(modelName) && !modelNames.has(modelName)) {
+                issues.push(moduleQualityIssue(moduleName, relativePath, `action XML references unknown res_model: ${modelName}`, 'error'));
+            }
+        }
+    }
     if (hasOdooStructures && !dataIncludesAccessCsv(data)) {
         issues.push(moduleIssue(moduleName, relativePath, 'missing security/ir.model.access.csv in manifest data'));
     }
@@ -257,7 +314,6 @@ export async function analyzeModuleDirectory(modulePath, moduleName = basename(m
     if (!(await directoryExists(join(modulePath, 'tests')))) {
         issues.push(moduleIssue(moduleName, relativePath, 'missing tests directory'));
     }
-    const allViewXml = [...viewXml, ...menuXml];
     const actionIds = declaredActionIds(allViewXml);
     for (const actionRef of menuActionReferences(menuXml)) {
         if (!actionIds.has(actionRef)) {

package/dist/postgres-diagnostics.js

@@ -124,13 +124,10 @@ index_health AS (
 wal_health AS (
   SELECT
     COALESCE((SELECT setting FROM pg_settings WHERE name = 'wal_level'), 'unavailable')::text AS wal_level,
-    COALESCE((SELECT setting FROM pg_settings WHERE name = 'archive_mode'), 'unavailable')::text AS wal_archive_mode,
-    COALESCE((SELECT COUNT(*) FROM pg_ls_waldir()), 0)::text AS wal_file_count,
-    COALESCE((SELECT SUM(size) FROM pg_ls_waldir()), 0)::text AS wal_directory_size_bytes
+    COALESCE((SELECT setting FROM pg_settings WHERE name = 'archive_mode'), 'unavailable')::text AS wal_archive_mode
 ),
 capacity_health AS (
   SELECT
-    COALESCE((SELECT pg_tablespace_size('pg_default')), 0)::text AS default_tablespace_size_bytes,
     COALESCE(
       (SELECT SUM(n_tup_ins + n_tup_upd + n_tup_del) FROM pg_stat_database WHERE datname IS NOT NULL),
       0
@@ -255,16 +252,30 @@ FROM (
   UNION ALL
   SELECT 'wal_archive_mode', wal_archive_mode FROM wal_health
   UNION ALL
-  SELECT 'wal_file_count', wal_file_count FROM wal_health
-  UNION ALL
-  SELECT 'wal_directory_size_bytes', wal_directory_size_bytes FROM wal_health
-  UNION ALL
-  SELECT 'default_tablespace_size_bytes', default_tablespace_size_bytes FROM capacity_health
-  UNION ALL
   SELECT 'database_write_activity_rows', database_write_activity_rows FROM capacity_health
 ) metrics
 ORDER BY metric;
 `.trim();
+export const POSTGRES_DIAGNOSTICS_OPTIONAL_QUERIES = [
+    {
+        id: 'wal-directory',
+        query: `
+SELECT metric || '|' || value
+FROM (
+  SELECT 'wal_file_count'::text AS metric, COALESCE((SELECT COUNT(*) FROM pg_ls_waldir()), 0)::text AS value
+  UNION ALL
+  SELECT 'wal_directory_size_bytes', COALESCE((SELECT SUM(size) FROM pg_ls_waldir()), 0)::text
+) metrics
+ORDER BY metric;
+`.trim(),
+    },
+    {
+        id: 'default-tablespace',
+        query: `
+SELECT 'default_tablespace_size_bytes'::text || '|' || COALESCE((SELECT pg_tablespace_size('pg_default')), 0)::text;
+`.trim(),
+    },
+];
 export const POSTGRES_DIAGNOSTIC_KEYS = [
     'database_count',
     'active_connections',

package/dist/source-actions.js

@@ -1,6 +1,6 @@
 import { defaultOdooVersion, readEnvironmentMetadata, replaceSourceRepos } from './environment.js';
 import { realGit, stageAll } from './git.js';
-import { listGitmoduleSources, readSourceManifest, sourceManifestEntriesFromMetadata, sourceReposFromManifest, syncManifestFromMetadataAndGitmodules, writeSourceManifest, } from './source-manifest.js';
+import { listGitmoduleSources, readSourceManifest, sourceManifestEntriesFromMetadata, sourceManifestPath, sourceReposFromManifest, syncManifestFromMetadataAndGitmodules, writeSourceManifest, } from './source-manifest.js';
 function cloneSourceEntries(entries) {
     return entries.map((entry) => ({
         ...entry,
@@ -47,6 +47,95 @@ export function sourceSyncJson(entries, target) {
         sources: cloneSourceEntries(entries),
     };
 }
+function sourceKey(entry) {
+    return `${entry.type}/${entry.path}`;
+}
+function sourceMap(entries) {
+    return new Map(entries.map((entry) => [sourceKey(entry), entry]));
+}
+function addonsEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sourceDriftChanges(file, currentEntries, nextEntries) {
+    const changes = [];
+    const current = sourceMap(currentEntries);
+    const next = sourceMap(nextEntries);
+    for (const [key, nextEntry] of next) {
+        const currentEntry = current.get(key);
+        if (!currentEntry) {
+            changes.push({ file, kind: 'add', source: key, after: cloneSourceEntries([nextEntry])[0] });
+            continue;
+        }
+        for (const field of ['url', 'branch']) {
+            const before = currentEntry[field] ?? '';
+            const after = nextEntry[field] ?? '';
+            if (before !== after) {
+                changes.push({ file, kind: 'update', source: key, field, before, after });
+            }
+        }
+        if (!addonsEqual(currentEntry.addons, nextEntry.addons)) {
+            changes.push({
+                file,
+                kind: 'update',
+                source: key,
+                field: 'addons',
+                before: [...currentEntry.addons],
+                after: [...nextEntry.addons],
+            });
+        }
+    }
+    for (const [key, currentEntry] of current) {
+        if (!next.has(key)) {
+            changes.push({ file, kind: 'remove', source: key, before: cloneSourceEntries([currentEntry])[0] });
+        }
+    }
+    return changes;
+}
+export async function sourceSyncPlan(target) {
+    const metadata = await readEnvironmentMetadata(target);
+    const manifest = await readSourceManifest(target);
+    const gitmodules = await listGitmoduleSources(target);
+    const fallbackBranch = metadata?.odooVersion ?? defaultOdooVersion;
+    const baseRepos = metadata?.sourceRepos.length ? metadata.sourceRepos : sourceReposFromManifest(manifest.sources);
+    const sources = syncManifestFromMetadataAndGitmodules(baseRepos, fallbackBranch, gitmodules);
+    return {
+        target,
+        sources,
+        changes: sourceDriftChanges(sourceManifestPath, manifest.sources, sources),
+    };
+}
+function renderValue(value) {
+    if (Array.isArray(value))
+        return `[${value.join(', ')}]`;
+    if (typeof value === 'object' && value)
+        return JSON.stringify(value);
+    return `"${value ?? ''}"`;
+}
+export function renderSourceSyncPlan(plan) {
+    if (plan.changes.length === 0) {
+        return 'Source manifest already in sync.';
+    }
+    return plan.changes
+        .map((change) => {
+        if (change.kind === 'add')
+            return `source manifest add ${change.source}`;
+        if (change.kind === 'remove')
+            return `source manifest remove ${change.source}`;
+        return `source manifest update ${change.source} ${change.field}: ${renderValue(change.before)} -> ${renderValue(change.after)}`;
+    })
+        .join('\n');
+}
+export function sourceSyncPlanJson(plan) {
+    return {
+        schemaVersion: 1,
+        command: 'source sync preview',
+        ok: true,
+        target: plan.target,
+        dryRun: true,
+        sources: cloneSourceEntries(plan.sources),
+        changes: plan.changes.map((change) => ({ ...change })),
+    };
+}
 export async function syncSources(options, git = realGit) {
     const metadata = await readEnvironmentMetadata(options.target);
     const manifest = await readSourceManifest(options.target);

package/dist/templates.js

@@ -208,8 +208,10 @@ resources/odoo/entrypoint.sh
 
 Development uses compose.yaml plus compose/dev.yaml by default.
 Set WPMOO_ENV=stage or WPMOO_ENV=prod only after providing production-grade secrets and volumes.
-In WPMOO_ENV=prod, module lifecycle commands such as install, update, and test
-require WPMOO_ALLOW_PROD_LIFECYCLE=1. Destructive database commands such as
+In WPMOO_ENV=stage, lifecycle commands such as install, update, stop, and
+restart require WPMOO_ALLOW_STAGE_LIFECYCLE=1. In WPMOO_ENV=prod, lifecycle
+commands such as install, update, test, stop, and restart require
+WPMOO_ALLOW_PROD_LIFECYCLE=1. Destructive database commands such as
 resetdb and real restore-snapshot require WPMOO_ALLOW_DESTRUCTIVE=1 in stage
 and prod. restore-snapshot --dry-run remains available for preview.
 For short-lived local approvals, add JSONL entries to \`.wpmoo/approvals.jsonl\`;
@@ -725,6 +727,84 @@ list_snapshots() {
   fi
 }
 
+list_snapshots_json() {
+  node --input-type=module <<'NODE'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const directories = ['backups/snapshots', 'backups', 'backup', 'snapshots'];
+const extensions = ['.dump', '.sql', '.sql.gz', '.zip', '.tar', '.tar.gz'];
+const now = Date.now();
+
+function snapshotStem(file) {
+  return file
+    .replace(/\\.filestore\\.tar\\.gz$/, '')
+    .replace(/\\.sql\\.gz$/, '')
+    .replace(/\\.tar\\.gz$/, '')
+    .replace(/\\.dump$/, '')
+    .replace(/\\.sql$/, '')
+    .replace(/\\.zip$/, '')
+    .replace(/\\.tar$/, '');
+}
+
+function hasSnapshotExtension(file) {
+  return extensions.some((extension) => file.endsWith(extension));
+}
+
+function readManifest(path) {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function manifestString(manifest, key) {
+  return manifest && typeof manifest[key] === 'string' ? manifest[key] : undefined;
+}
+
+const snapshots = [];
+for (const directory of directories) {
+  if (!existsSync(directory)) continue;
+
+  for (const file of readdirSync(directory).sort()) {
+    if (file.endsWith('.filestore.tar.gz') || !hasSnapshotExtension(file)) continue;
+
+    const dumpPath = join(directory, file);
+    const stats = statSync(dumpPath);
+    if (!stats.isFile()) continue;
+
+    const name = snapshotStem(file);
+    const manifestPath = join(directory, name + '.json');
+    const manifest = readManifest(manifestPath);
+    const manifestDump = manifestString(manifest, 'dump');
+    const manifestFilestore = manifestString(manifest, 'filestore');
+    const filestorePath = join(directory, manifestFilestore || name + '.filestore.tar.gz');
+    const createdAtMs = Date.parse(manifestString(manifest, 'created_at') || '');
+    const effectiveCreatedAtMs = Number.isFinite(createdAtMs) ? createdAtMs : stats.mtimeMs;
+
+    snapshots.push({
+      name: manifestString(manifest, 'name') || name,
+      path: dumpPath,
+      dumpPath: manifestDump ? join(directory, manifestDump) : dumpPath,
+      ...(existsSync(manifestPath) ? { manifestPath } : {}),
+      ...(manifestString(manifest, 'database') ? { databaseName: manifestString(manifest, 'database') } : {}),
+      createdAtMs: effectiveCreatedAtMs,
+      createdAt: new Date(effectiveCreatedAtMs).toISOString(),
+      mtimeMs: stats.mtimeMs,
+      ageMs: Math.max(0, now - effectiveCreatedAtMs),
+      filestorePath,
+      filestoreStatus: existsSync(filestorePath) ? 'found' : 'missing',
+    });
+  }
+}
+
+snapshots.sort((left, right) => right.createdAtMs - left.createdAtMs || left.path.localeCompare(right.path));
+console.log(JSON.stringify({ schemaVersion: 1, command: 'snapshot list', ok: true, snapshots }, null, 2));
+NODE
+}
+
 require_recent_snapshot_or_override() {
   local command="$1"
   local env_name
@@ -834,6 +914,8 @@ case "$command" in
   "stop")
     shift
     require_no_args "$command" "$@"
+    require_stage_lifecycle_allowed "$command"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/down.sh
     ;;
   "logs")
@@ -854,6 +936,8 @@ case "$command" in
   "restart")
     shift
     require_no_args "$command" "$@"
+    require_stage_lifecycle_allowed "$command"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/restart.sh
     ;;
   "shell")
@@ -898,10 +982,32 @@ case "$command" in
     ;;
   "snapshot")
     shift
-    if [[ "\${1:-}" == "--list" ]]; then
-      shift
-      require_no_args "$command" "$@"
-      list_snapshots
+    if [[ "\${1:-}" == "--list" || "\${1:-}" == "--json" ]]; then
+      list_requested=0
+      json_requested=0
+      while [[ "$#" -gt 0 ]]; do
+        case "$1" in
+          "--list")
+            list_requested=1
+            shift
+            ;;
+          "--json")
+            json_requested=1
+            shift
+            ;;
+          *)
+            fail_usage "$command"
+            ;;
+        esac
+      done
+      if [[ "$list_requested" -ne 1 ]]; then
+        fail_usage "$command"
+      fi
+      if [[ "$json_requested" -eq 1 ]]; then
+        list_snapshots_json
+      else
+        list_snapshots
+      fi
       exit 0
     fi
     positional_args "$command" 0 2 "$@"

package/docs/1-0-readiness.md

@@ -65,8 +65,9 @@ Ready:
 
 Ready:
 
-- Stage `install` and `update` require `WPMOO_ALLOW_STAGE_LIFECYCLE=1`.
-- Production `install`, `update`, and `test` require
+- Stage `install`, `update`, `stop`, and `restart` require
+  `WPMOO_ALLOW_STAGE_LIFECYCLE=1`.
+- Production `install`, `update`, `test`, `stop`, and `restart` require
   `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
 - Destructive database commands require `WPMOO_ALLOW_DESTRUCTIVE=1` in stage
   and production.

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
@@ -79,8 +85,8 @@ Current JSON contract notes:
 | 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_STAGE_LIFECYCLE=1` | Allows `install`, `update`, `stop`, and `restart` in stage. |
+| `WPMOO_ALLOW_PROD_LIFECYCLE=1` | Allows `install`, `update`, `test`, `stop`, and `restart` 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. |
@@ -121,6 +127,7 @@ approval. Expired, malformed, or mismatched entries are ignored.
 | Command Family | Stage | Production |
 | --- | --- | --- |
 | `install`, `update` | Requires `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Requires `WPMOO_ALLOW_PROD_LIFECYCLE=1` |
+| `stop`, `restart` | 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 |

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