@wpmoo/toolkit 0.9.15 → 0.9.16

package/README.md

@@ -144,6 +144,7 @@ Every cockpit action maps to a direct command, so the same workflow can be used
 ./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`.
 `resetdb` and real `restore-snapshot` require `WPMOO_ALLOW_DESTRUCTIVE=1` in `stage` and `prod`.
 `restore-snapshot --dry-run` remains allowed for preview.
@@ -155,7 +156,7 @@ npx @wpmoo/toolkit add-module --repo sale-workflow --module sale_order_line_no_d
 npx @wpmoo/toolkit remove-module --repo sale-workflow --module sale_order_line_no_discount --source-type oca
 ```
 
-`add-module` creates a minimal Odoo module skeleton with `__init__.py`, `__manifest__.py`, `models/<module>.py`, `models/__init__.py`, `security/ir.model.access.csv`, `views/<module>_views.xml`, `views/<module>_menus.xml`, and `tests/test_<module>.py`. The view XML adds list/tree and form views; the menu XML adds a basic Odoo action and menu entry; the test skeleton adds a post-install TransactionCase smoke test. Module names must be lower `snake_case`; use letters, numbers, and underscores only.
+`add-module` creates a minimal Odoo module skeleton with `__init__.py`, `__manifest__.py`, `models/<module>.py`, `models/__init__.py`, `security/ir.model.access.csv`, `views/<module>_views.xml`, `views/<module>_menus.xml`, and `tests/test_<module>.py`. The view XML adds list/tree and form views; the menu XML adds a basic Odoo action and internal-user menu entry; the test skeleton adds a post-install TransactionCase smoke test. WPMoo reports scaffold quality after generation and `status` reports installable modules, non-installable modules, and modules without actionable menus. Module names must be lower `snake_case`; use letters, numbers, and underscores only.
 
 For automation and VS Code cockpit integration, selected commands support JSON output:
 
@@ -176,6 +177,19 @@ such as database size, sessions currently running queries with
 `doctor --json --postgres` includes a structured `postgres` object for automation.
 Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
+## Release Artifacts
+
+WPMoo Toolkit releases are valid when the required npm artifacts publish
+successfully:
+
+- `@wpmoo/toolkit`
+- `@wpmoo/odoo`
+- `@wpmoo/odoo-dev`
+
+The unscoped `wpmoo` short alias is optional. If npm returns `E404` or rejects
+that alias during the publish workflow, the workflow reports a non-blocking
+warning while keeping the scoped package release valid.
+
 ## Documentation
 
 - [External Resources](docs/external-resources.md)

package/dist/cli.js

@@ -1628,10 +1628,13 @@ export function isCliEntrypoint(metaUrl, argvPath = process.argv[1]) {
         return metaUrl === pathToFileURL(argvPath).href;
     }
 }
+export function formatCliErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.trim() || 'Unknown WPMoo Toolkit error';
+}
 if (isCliEntrypoint(import.meta.url)) {
     runCli().catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(message);
+        console.error(formatCliErrorMessage(error));
         process.exit(1);
     });
 }

package/dist/daily-actions.js

@@ -158,9 +158,15 @@ function isDestructiveCommand(command, args) {
 function isProductionLifecycleCommand(command) {
     return command === 'install' || command === 'update' || command === 'test';
 }
+function isStageLifecycleCommand(command) {
+    return command === 'install' || command === 'update';
+}
 function destructiveCommandError(command, envName) {
     return `Refusing destructive command '${command}' in WPMOO_ENV=${envName}. Set WPMOO_ALLOW_DESTRUCTIVE=1 to run it intentionally.`;
 }
+function stageLifecycleCommandError(command) {
+    return `Refusing stage lifecycle command '${command}' in WPMOO_ENV=stage. Set WPMOO_ALLOW_STAGE_LIFECYCLE=1 to run it intentionally.`;
+}
 function productionLifecycleCommandError(command) {
     return `Refusing production lifecycle command '${command}' in WPMOO_ENV=prod. Set WPMOO_ALLOW_PROD_LIFECYCLE=1 to run it intentionally.`;
 }
@@ -192,6 +198,20 @@ async function assertProductionLifecycleCommandAllowed(command, cwd) {
         throw new Error(productionLifecycleCommandError(command));
     }
 }
+async function assertStageLifecycleCommandAllowed(command, cwd) {
+    if (!isStageLifecycleCommand(command)) {
+        return;
+    }
+    const env = await readEnvFile(cwd);
+    const envName = process.env.WPMOO_ENV?.trim() || selectedComposeEnvironment(env);
+    if (envName !== 'stage') {
+        return;
+    }
+    const allowStageLifecycle = process.env.WPMOO_ALLOW_STAGE_LIFECYCLE?.trim() || env?.get('WPMOO_ALLOW_STAGE_LIFECYCLE')?.trim();
+    if (allowStageLifecycle !== '1') {
+        throw new Error(stageLifecycleCommandError(command));
+    }
+}
 async function assertEnvironmentRoot(cwd) {
     try {
         await access(join(cwd, markerPath));
@@ -214,6 +234,7 @@ export async function dailyActionPlan(command, argv, cwd = process.cwd()) {
     await assertEnvironmentRoot(cwd);
     const scriptPath = await assertScriptExists(cwd, dailyActionScripts[command]);
     const args = scriptArgs(command, argv);
+    await assertStageLifecycleCommandAllowed(command, cwd);
     await assertProductionLifecycleCommandAllowed(command, cwd);
     await assertDestructiveCommandAllowed(command, args, cwd);
     return {

package/dist/doctor.js

@@ -70,6 +70,28 @@ WITH metrics(metric, value) AS (
     FROM pg_database
     WHERE datistemplate = false
   UNION ALL
+  SELECT 'largest_database_name', COALESCE(
+    (
+      SELECT datname
+      FROM pg_database
+      WHERE datistemplate = false
+      ORDER BY pg_database_size(datname) DESC, datname
+      LIMIT 1
+    ),
+    'unavailable'
+  )
+  UNION ALL
+  SELECT 'largest_database_size_bytes', COALESCE(
+    (
+      SELECT pg_database_size(datname)::text
+      FROM pg_database
+      WHERE datistemplate = false
+      ORDER BY pg_database_size(datname) DESC, datname
+      LIMIT 1
+    ),
+    '0'
+  )
+  UNION ALL
   SELECT 'slow_query_logging', COALESCE(
     (SELECT setting || unit FROM pg_settings WHERE name = 'log_min_duration_statement'),
     'unavailable'
@@ -82,6 +104,21 @@ WITH metrics(metric, value) AS (
       ELSE 'unavailable'
     END
   UNION ALL
+  SELECT 'pg_stat_statements_available_version', COALESCE(
+    (SELECT default_version FROM pg_available_extensions WHERE name = 'pg_stat_statements'),
+    'unavailable'
+  )
+  UNION ALL
+  SELECT 'pg_stat_statements_installed_version', COALESCE(
+    (SELECT extversion FROM pg_extension WHERE extname = 'pg_stat_statements'),
+    ''
+  )
+  UNION ALL
+  SELECT 'shared_preload_libraries', COALESCE(
+    (SELECT setting FROM pg_settings WHERE name = 'shared_preload_libraries'),
+    'unavailable'
+  )
+  UNION ALL
   SELECT 'shared_buffers', COALESCE(
     (SELECT setting FROM pg_settings WHERE name = 'shared_buffers'),
     'unavailable'
@@ -95,13 +132,33 @@ ORDER BY CASE metric
   WHEN 'connection_count' THEN 3
   WHEN 'max_connections' THEN 4
   WHEN 'total_database_size_bytes' THEN 5
-  WHEN 'slow_query_logging' THEN 6
-  WHEN 'pg_stat_statements' THEN 7
-  WHEN 'shared_buffers' THEN 8
+  WHEN 'largest_database_name' THEN 6
+  WHEN 'largest_database_size_bytes' THEN 7
+  WHEN 'slow_query_logging' THEN 8
+  WHEN 'pg_stat_statements' THEN 9
+  WHEN 'pg_stat_statements_available_version' THEN 10
+  WHEN 'pg_stat_statements_installed_version' THEN 11
+  WHEN 'shared_preload_libraries' THEN 12
+  WHEN 'shared_buffers' THEN 13
   ELSE 99
 END;
 `.trim();
 const postgresDiagnosticKeys = [
+    'database_count',
+    'active_connections',
+    'connection_count',
+    'max_connections',
+    'total_database_size_bytes',
+    'largest_database_name',
+    'largest_database_size_bytes',
+    'slow_query_logging',
+    'pg_stat_statements',
+    'pg_stat_statements_available_version',
+    'pg_stat_statements_installed_version',
+    'shared_preload_libraries',
+    'shared_buffers',
+];
+const requiredPostgresDiagnosticKeys = [
     'database_count',
     'active_connections',
     'connection_count',
@@ -152,7 +209,7 @@ function renderPostgresDiagnostics(diagnostics) {
     return parts.length > 0 ? `OK PostgreSQL diagnostics ${parts.join(' ')}` : undefined;
 }
 function missingPostgresDiagnosticKeys(diagnostics) {
-    return postgresDiagnosticKeys.filter((key) => !diagnostics[key]);
+    return requiredPostgresDiagnosticKeys.filter((key) => !diagnostics[key]);
 }
 function unavailablePostgresDiagnosticsWarning(diagnostics, missingKeys) {
     return Object.keys(diagnostics).length === 0
@@ -172,6 +229,7 @@ function malformedPostgresDiagnosticKeys(diagnostics) {
         'connection_count',
         'max_connections',
         'total_database_size_bytes',
+        'largest_database_size_bytes',
     ];
     return numericKeys.filter((key) => diagnostics[key] !== undefined && integerDiagnostic(diagnostics[key]) === undefined);
 }
@@ -197,11 +255,19 @@ function postgresConnectionUtilizationWarning(diagnostics) {
 }
 function postgresSlowQueryLoggingWarning(diagnostics) {
     const slowQueryLogging = diagnostics.slow_query_logging?.trim();
-    if (!slowQueryLogging || !/^-1\s*(?:ms)?$/iu.test(slowQueryLogging)) {
+    if (!slowQueryLogging || (!/^-1\s*(?:ms)?$/iu.test(slowQueryLogging) && !/^off$/iu.test(slowQueryLogging))) {
         return undefined;
     }
     return `PostgreSQL slow-query logging is disabled (log_min_duration_statement=${slowQueryLogging}). Enable it before performance triage.`;
 }
+function postgresExtensionVisibilityWarning(diagnostics) {
+    if (diagnostics.pg_stat_statements === 'available' &&
+        diagnostics.pg_stat_statements_available_version &&
+        !diagnostics.pg_stat_statements_installed_version) {
+        return 'PostgreSQL pg_stat_statements is available but not installed. Install it before query-level performance triage.';
+    }
+    return undefined;
+}
 function structuredPostgresDiagnostics(diagnostics) {
     const structured = {};
     const databaseCount = integerDiagnostic(diagnostics.database_count);
@@ -210,6 +276,7 @@ function structuredPostgresDiagnostics(diagnostics) {
     const maxConnections = integerDiagnostic(diagnostics.max_connections);
     const connectionUtilizationPct = postgresConnectionUtilizationPct(diagnostics);
     const totalDatabaseSizeBytes = integerDiagnostic(diagnostics.total_database_size_bytes);
+    const largestDatabaseSizeBytes = integerDiagnostic(diagnostics.largest_database_size_bytes);
     if (databaseCount !== undefined)
         structured.databaseCount = databaseCount;
     if (activeConnections !== undefined)
@@ -222,10 +289,22 @@ function structuredPostgresDiagnostics(diagnostics) {
         structured.connectionUtilizationPct = connectionUtilizationPct;
     if (totalDatabaseSizeBytes !== undefined)
         structured.totalDatabaseSizeBytes = totalDatabaseSizeBytes;
+    if (diagnostics.largest_database_name)
+        structured.largestDatabaseName = diagnostics.largest_database_name;
+    if (largestDatabaseSizeBytes !== undefined)
+        structured.largestDatabaseSizeBytes = largestDatabaseSizeBytes;
     if (diagnostics.slow_query_logging)
         structured.slowQueryLogging = diagnostics.slow_query_logging;
     if (diagnostics.pg_stat_statements)
         structured.pgStatStatements = diagnostics.pg_stat_statements;
+    if (diagnostics.pg_stat_statements_available_version) {
+        structured.pgStatStatementsAvailableVersion = diagnostics.pg_stat_statements_available_version;
+    }
+    if (diagnostics.pg_stat_statements_installed_version) {
+        structured.pgStatStatementsInstalledVersion = diagnostics.pg_stat_statements_installed_version;
+    }
+    if (diagnostics.shared_preload_libraries)
+        structured.sharedPreloadLibraries = diagnostics.shared_preload_libraries;
     if (diagnostics.shared_buffers)
         structured.sharedBuffers = diagnostics.shared_buffers;
     return structured;
@@ -648,6 +727,10 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
                 if (slowQueryLoggingWarning) {
                     warnings.push(slowQueryLoggingWarning);
                 }
+                const extensionVisibilityWarning = postgresExtensionVisibilityWarning(postgresDiagnostics);
+                if (extensionVisibilityWarning) {
+                    warnings.push(extensionVisibilityWarning);
+                }
             }
             else {
                 const warning = malformedKeys.length > 0

package/dist/help.js

@@ -85,7 +85,8 @@ Daily actions:
   Generated environments also include ./moo for local compose commands such as ./moo start.
   Use ./moo or npx @wpmoo/toolkit with the same daily action arguments.
 
-Production command guards:
+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.
   resetdb and real restore-snapshot require WPMOO_ALLOW_DESTRUCTIVE=1 in stage/prod.
   restore-snapshot --dry-run remains allowed for preview.
@@ -128,7 +129,8 @@ Task recipes:
   Add module:
     npx @wpmoo/toolkit add-module --repo <source-repo> --module <module-name> --source-type private|oca|external
     Creates a minimal skeleton: __init__.py, __manifest__.py, models/<module>.py, models/__init__.py, security/ir.model.access.csv, views/<module>_views.xml, views/<module>_menus.xml, and tests/test_<module>.py.
-    The view XML adds list/tree and form views; the menu XML adds a basic Odoo action and menu entry; the test skeleton adds a post-install TransactionCase smoke test.
+    The view XML adds list/tree and form views; the menu XML adds a basic Odoo action and internal-user menu entry; the test skeleton adds a post-install TransactionCase smoke test.
+    WPMoo reports scaffold quality after generation and status reports installable modules, non-installable modules, and modules without actionable menus.
     Module names must be lower snake_case; use letters, numbers, and underscores only.
   Remove module:
     npx @wpmoo/toolkit remove-module --repo <source-repo> --module <module-name> --source-type private|oca|external

package/dist/module-actions.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { addModuleToSourceRepoInAddonsYaml, removeModuleFromSourceRepoInAddonsYaml, } from './addons-yaml.js';
 import { readEnvironmentMetadata, replaceSourceRepos } from './environment.js';
 import { realGit, stageAll } from './git.js';
+import { analyzeModuleDirectory } from './module-quality.js';
 import { supportedOdooVersions } from './odoo-versions.js';
 import { pathUnderBase, validateModuleName, validateRepoPath } from './path-validation.js';
 import { listModuleRepos, readAddonsYaml, writeAddonsYaml } from './repo-actions.js';
@@ -138,8 +139,8 @@ function menuXmlContent(moduleName, odooVersion) {
         <field name="view_mode">${actionViewMode(odooVersion)}</field>
     </record>
 
-    <menuitem id="menu_${moduleName}_root" name="${moduleTitle}" sequence="10"/>
-    <menuitem id="menu_${moduleName}" name="${moduleTitle}" parent="menu_${moduleName}_root" action="action_${moduleName}" sequence="10"/>
+    <menuitem id="menu_${moduleName}_root" name="${moduleTitle}" groups="base.group_user" sequence="10"/>
+    <menuitem id="menu_${moduleName}" name="${moduleTitle}" parent="menu_${moduleName}_root" action="action_${moduleName}" groups="base.group_user" sequence="10"/>
 </odoo>
 `;
 }
@@ -176,6 +177,123 @@ async function writeIfMissing(path, content) {
         await writeFile(path, content, 'utf8');
     }
 }
+async function fileContains(path, expected) {
+    try {
+        return (await readFile(path, 'utf8')).includes(expected);
+    }
+    catch {
+        return false;
+    }
+}
+async function moduleScaffoldChecks(target, sourceType, repoPath, moduleName, includeRegistration) {
+    const destination = modulePath(target, sourceType, repoPath, moduleName);
+    const technicalName = modelTechnicalName(moduleName);
+    const modelId = technicalName.replace(/\./g, '_');
+    const checks = [
+        {
+            id: 'manifest',
+            label: 'manifest',
+            ok: (await fileContains(join(destination, '__manifest__.py'), '"installable": True')) &&
+                (await fileContains(join(destination, '__manifest__.py'), '"security/ir.model.access.csv"')) &&
+                (await fileContains(join(destination, '__manifest__.py'), `"views/${moduleName}_views.xml"`)) &&
+                (await fileContains(join(destination, '__manifest__.py'), `"views/${moduleName}_menus.xml"`)),
+            details: 'missing installable flag or required data entries',
+        },
+        {
+            id: 'model',
+            label: 'model',
+            ok: (await fileContains(join(destination, '__init__.py'), 'from . import models')) &&
+                (await fileContains(join(destination, 'models/__init__.py'), `from . import ${moduleName}`)) &&
+                (await fileContains(join(destination, `models/${moduleName}.py`), `_name = "${technicalName}"`)),
+            details: `missing model import or _name ${technicalName}`,
+        },
+        {
+            id: 'access',
+            label: 'access',
+            ok: await fileContains(join(destination, 'security/ir.model.access.csv'), `model_${modelId}`),
+            details: `missing access CSV model_${modelId}`,
+        },
+        {
+            id: 'views',
+            label: 'views',
+            ok: (await fileContains(join(destination, `views/${moduleName}_views.xml`), `model">${technicalName}</field>`)) &&
+                (await fileContains(join(destination, `views/${moduleName}_views.xml`), '<form ')),
+            details: `missing views for ${technicalName}`,
+        },
+        {
+            id: 'menus',
+            label: 'menus',
+            ok: (await fileContains(join(destination, `views/${moduleName}_menus.xml`), `id="action_${moduleName}"`)) &&
+                (await fileContains(join(destination, `views/${moduleName}_menus.xml`), 'model="ir.actions.act_window"')) &&
+                (await fileContains(join(destination, `views/${moduleName}_menus.xml`), `action="action_${moduleName}"`)) &&
+                (await fileContains(join(destination, `views/${moduleName}_menus.xml`), 'groups="base.group_user"')),
+            details: `missing action menu action_${moduleName}`,
+        },
+        {
+            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',
+        },
+    ];
+    if (includeRegistration) {
+        checks.push({
+            id: 'registration',
+            label: 'registration',
+            ok: await moduleRegistrationPresent(target, sourceType, repoPath, moduleName),
+            details: 'missing module registration in addons.yaml, source manifest, or metadata',
+        });
+    }
+    return checks;
+}
+async function moduleRegistrationPresent(target, sourceType, repoPath, moduleName) {
+    if (sourceType === 'private' && (await usesAddonsYaml(target))) {
+        try {
+            const addonsYaml = await readAddonsYaml(target);
+            return addonsYaml.includes(`private/${repoPath}:`) && addonsYaml.includes(`  - ${moduleName}`);
+        }
+        catch {
+            return false;
+        }
+    }
+    const manifest = await readSourceManifest(target);
+    if (manifest.sources.some((entry) => entry.type === sourceType && entry.path === repoPath && entry.addons.includes(moduleName))) {
+        return true;
+    }
+    const metadata = await readEnvironmentMetadata(target);
+    return Boolean(metadata?.sourceRepos?.some((entry) => normalizeSourceType(entry.sourceType) === sourceType &&
+        entry.path === repoPath &&
+        entry.addons.includes(moduleName)));
+}
+function buildModuleScaffoldReport(moduleName, repoPath, sourceType, path, checks) {
+    return {
+        moduleName,
+        repoPath,
+        sourceType,
+        path,
+        checks: checks.map(({ details, ...check }) => (check.ok ? check : { ...check, details })),
+        warnings: checks.filter((check) => !check.ok).map((check) => `${check.label} ${check.details ?? 'failed'}`),
+        summary: `Module scaffold checks passed: ${checks.map((check) => check.label).join(', ')}.`,
+    };
+}
+async function assertGeneratedModuleScaffold(target, sourceType, repoPath, moduleName) {
+    const quality = await analyzeModuleDirectory(modulePath(target, sourceType, repoPath, moduleName), moduleName, `odoo/custom/src/${sourceType}/${repoPath}/${moduleName}`);
+    const checks = await moduleScaffoldChecks(target, sourceType, repoPath, moduleName, false);
+    const failed = checks.filter((check) => !check.ok);
+    if (!quality.installable) {
+        failed.unshift({ id: 'manifest-installable', label: 'manifest', ok: false, details: 'missing installable=True in __manifest__.py' });
+    }
+    if (!quality.hasMenuAction) {
+        failed.unshift({ id: 'menu-action', label: 'menus', ok: false, details: `missing action menu action_${moduleName}` });
+    }
+    if (failed.length > 0) {
+        throw new Error(`Generated module scaffold validation failed for ${moduleName}: ${failed[0]?.label ?? 'unknown'} ${failed[0]?.details ?? 'failed'}`);
+    }
+}
+export function renderModuleScaffoldReport(report) {
+    return report.summary;
+}
 async function usesAddonsYaml(target) {
     const metadata = await readEnvironmentMetadata(target);
     return metadata?.engine !== 'compose';
@@ -233,6 +351,20 @@ async function updateModuleRegistration(target, sourceType, repoPath, moduleName
     await updateSourceManifestModuleRegistration(target, sourceType, repoPath, moduleName, mode);
     await updateMetadataModuleRegistration(target, sourceType, repoPath, moduleName, mode);
 }
+async function assertModuleCleanBeforeDelete(target, sourceType, repoPath, moduleName, git) {
+    const repoRoot = sourceRepoPath(target, sourceType, repoPath);
+    try {
+        const result = await git.run(repoRoot, ['status', '--short', '--', moduleName]);
+        if (result.stdout.trim()) {
+            throw new Error(`Refusing to delete module ${moduleName} because it has dirty git changes in source repo ${repoPath}.`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('Refusing to delete module ')) {
+            throw error;
+        }
+    }
+}
 export async function addModuleToSourceRepo(options, git = realGit) {
     const repoPath = validateRepoPath(options.repoPath);
     const moduleName = validateModuleName(options.moduleName);
@@ -253,6 +385,7 @@ export async function addModuleToSourceRepo(options, git = realGit) {
     await writeIfMissing(join(destination, `views/${moduleName}_views.xml`), viewXmlContent(moduleName, odooVersion));
     await writeIfMissing(join(destination, `views/${moduleName}_menus.xml`), menuXmlContent(moduleName, odooVersion));
     await writeIfMissing(join(destination, 'views/.gitkeep'), '');
+    await assertGeneratedModuleScaffold(options.target, sourceType, repoPath, moduleName);
     if (sourceType === 'private' && (await usesAddonsYaml(options.target))) {
         const addonsYaml = await readAddonsYaml(options.target);
         await writeAddonsYaml(options.target, addModuleToSourceRepoInAddonsYaml(addonsYaml, repoPath, moduleName));
@@ -262,6 +395,7 @@ export async function addModuleToSourceRepo(options, git = realGit) {
         await stageAll(git, sourceRepoPath(options.target, sourceType, repoPath));
         await stageAll(git, options.target);
     }
+    return buildModuleScaffoldReport(moduleName, repoPath, sourceType, destination, await moduleScaffoldChecks(options.target, sourceType, repoPath, moduleName, true));
 }
 export async function listModulesInSourceRepo(target, repoPath, sourceType) {
     const safeRepoPath = validateRepoPath(repoPath);
@@ -319,6 +453,9 @@ export async function removeModuleFromSourceRepo(options, git = realGit) {
     const repoPath = validateRepoPath(options.repoPath);
     const moduleName = validateModuleName(options.moduleName);
     const sourceType = normalizeSourceType(options.sourceType);
+    if (options.deleteFiles) {
+        await assertModuleCleanBeforeDelete(options.target, sourceType, repoPath, moduleName, git);
+    }
     if (sourceType === 'private' && (await usesAddonsYaml(options.target))) {
         const addonsYaml = await readAddonsYaml(options.target);
         await writeAddonsYaml(options.target, removeModuleFromSourceRepoInAddonsYaml(addonsYaml, repoPath, moduleName));

package/dist/module-quality.js

@@ -0,0 +1,111 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+export function emptyModuleQualitySummary() {
+    return {
+        totalModules: 0,
+        installableModules: 0,
+        nonInstallableModules: 0,
+        modulesWithMenuActions: 0,
+        modulesMissingMenuActions: 0,
+        issues: [],
+    };
+}
+export function isInstallableManifest(content) {
+    return /["']installable["']\s*:\s*(?:True|true)\b/u.test(content);
+}
+export function hasActionableMenuXml(content, moduleName) {
+    const actionId = `action_${moduleName}`;
+    return (content.includes(`id="${actionId}"`) &&
+        content.includes('model="ir.actions.act_window"') &&
+        content.includes(`action="${actionId}"`));
+}
+async function readMenusXml(modulePath) {
+    try {
+        const entries = await readdir(join(modulePath, 'views'), { withFileTypes: true });
+        const menuFiles = entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith('_menus.xml'))
+            .map((entry) => join(modulePath, 'views', entry.name));
+        return Promise.all(menuFiles.map((path) => readFile(path, 'utf8')));
+    }
+    catch {
+        return [];
+    }
+}
+export async function analyzeModuleDirectory(modulePath, moduleName = basename(modulePath), relativePath = modulePath) {
+    const issues = [];
+    let installable = false;
+    try {
+        installable = isInstallableManifest(await readFile(join(modulePath, '__manifest__.py'), 'utf8'));
+    }
+    catch {
+        installable = false;
+    }
+    if (!installable) {
+        issues.push({
+            moduleName,
+            path: relativePath,
+            issue: 'missing installable=True in __manifest__.py',
+        });
+    }
+    const menuXml = await readMenusXml(modulePath);
+    const hasMenuAction = menuXml.some((content) => hasActionableMenuXml(content, moduleName));
+    if (!hasMenuAction) {
+        issues.push({
+            moduleName,
+            path: relativePath,
+            issue: 'missing actionable menu XML',
+        });
+    }
+    return { moduleName, relativePath, installable, hasMenuAction, issues };
+}
+export function addModuleQualityResult(summary, result) {
+    return {
+        totalModules: summary.totalModules + 1,
+        installableModules: summary.installableModules + (result.installable ? 1 : 0),
+        nonInstallableModules: summary.nonInstallableModules + (result.installable ? 0 : 1),
+        modulesWithMenuActions: summary.modulesWithMenuActions + (result.hasMenuAction ? 1 : 0),
+        modulesMissingMenuActions: summary.modulesMissingMenuActions + (result.hasMenuAction ? 0 : 1),
+        issues: [...summary.issues, ...result.issues],
+    };
+}
+export function mergeModuleQualitySummaries(left, right) {
+    return {
+        totalModules: left.totalModules + right.totalModules,
+        installableModules: left.installableModules + right.installableModules,
+        nonInstallableModules: left.nonInstallableModules + right.nonInstallableModules,
+        modulesWithMenuActions: left.modulesWithMenuActions + right.modulesWithMenuActions,
+        modulesMissingMenuActions: left.modulesMissingMenuActions + right.modulesMissingMenuActions,
+        issues: [...left.issues, ...right.issues],
+    };
+}
+export async function scanModuleQuality(root, target) {
+    try {
+        const rootStat = await stat(root);
+        if (!rootStat.isDirectory())
+            return emptyModuleQualitySummary();
+    }
+    catch {
+        return emptyModuleQualitySummary();
+    }
+    let summary = emptyModuleQualitySummary();
+    const stack = [root];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const entries = await readdir(current, { withFileTypes: true });
+        let hasManifest = false;
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name === '__manifest__.py') {
+                hasManifest = true;
+            }
+            else if (entry.isDirectory()) {
+                stack.push(join(current, entry.name));
+            }
+        }
+        if (hasManifest) {
+            summary = addModuleQualityResult(summary, await analyzeModuleDirectory(current, basename(current), relative(target, current)));
+        }
+    }
+    return summary;
+}

package/dist/status.js

@@ -1,7 +1,8 @@
-import { access, readdir, readFile, stat } from 'node:fs/promises';
+import { access, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { detectComposeLayout, readEnvFile, selectedComposeEnvironment } from './compose-layout.js';
 import { defaultOdooVersion, markerPath } from './environment.js';
+import { emptyModuleQualitySummary, mergeModuleQualitySummaries, scanModuleQuality, } from './module-quality.js';
 import { isValidPathSegment, validateRepoPath } from './path-validation.js';
 const validSourceTypes = ['private', 'oca', 'external'];
 function normalizeSourceType(sourceType) {
@@ -84,33 +85,6 @@ async function missingCoreFiles(target, odooVersion) {
     missing.push(...composeLayout.missingFiles);
     return { missing, composeFiles: composeLayout.files, composeErrors: composeLayout.errors };
 }
-async function countModuleCandidatesInRepoPath(path) {
-    if (!(await pathExists(path)))
-        return 0;
-    const rootStat = await stat(path);
-    if (!rootStat.isDirectory())
-        return 0;
-    let count = 0;
-    const stack = [path];
-    while (stack.length > 0) {
-        const current = stack.pop();
-        if (!current)
-            continue;
-        const entries = await readdir(current, { withFileTypes: true });
-        let hasManifest = false;
-        for (const entry of entries) {
-            if (entry.isFile() && entry.name === '__manifest__.py') {
-                hasManifest = true;
-            }
-            else if (entry.isDirectory()) {
-                stack.push(join(current, entry.name));
-            }
-        }
-        if (hasManifest)
-            count += 1;
-    }
-    return count;
-}
 function summaryText(status) {
     if (status.kind === 'no_environment')
         return 'No WPMoo environment detected.';
@@ -167,10 +141,11 @@ export async function getEnvironmentStatus(target) {
         : defaultOdooVersion;
     const { sourceRepoPaths, sourceRepoLocations, invalidSourceRepoPaths } = sourceRepoPathsFromMetadata(metadata);
     const repoRoots = sourceRepoLocations.map(({ sourceType, path }) => sourceRepoPath(target, sourceType, path));
-    let moduleCandidateCount = 0;
+    let moduleQuality = emptyModuleQualitySummary();
     for (const repoRoot of repoRoots) {
-        moduleCandidateCount += await countModuleCandidatesInRepoPath(repoRoot);
+        moduleQuality = mergeModuleQualitySummaries(moduleQuality, await scanModuleQuality(repoRoot, target));
     }
+    const moduleCandidateCount = moduleQuality.totalModules;
     const { missing: missingFiles, composeFiles, composeErrors, } = await missingCoreFiles(target, odooVersion);
     let recommendedNextAction = 'Run npx @wpmoo/toolkit doctor for deep checks or ./moo start.';
     if (invalidSourceRepoPaths.length > 0) {
@@ -195,6 +170,7 @@ export async function getEnvironmentStatus(target) {
         sourceRepoPaths,
         invalidSourceRepoPaths,
         moduleCandidateCount,
+        moduleQuality,
         composeFiles,
         composeErrors,
         missingCoreFiles: missingFiles,
@@ -229,6 +205,12 @@ export function renderEnvironmentStatus(status) {
         lines.push(`Invalid source repo paths: ${status.invalidSourceRepoPaths.join(', ')}`);
     }
     lines.push(`Module candidates: ${status.moduleCandidateCount}`);
+    lines.push(`Module quality: ${status.moduleQuality.installableModules} installable, ${status.moduleQuality.nonInstallableModules} non-installable, ${status.moduleQuality.modulesMissingMenuActions} missing menu actions.`);
+    if (status.moduleQuality.issues.length > 0) {
+        lines.push(`Module quality issues: ${status.moduleQuality.issues
+            .map((issue) => `${issue.path}: ${issue.issue}`)
+            .join('; ')}`);
+    }
     lines.push(`Missing core files: ${status.missingCoreFiles.length > 0 ? status.missingCoreFiles.join(', ') : '(none)'}`);
     lines.push(`Next: ${status.recommendedNextAction}`);
     return lines.join('\n');

package/dist/templates.js

@@ -596,6 +596,23 @@ allow_prod_lifecycle() {
   [[ "$value" == "1" ]]
 }
 
+allow_stage_lifecycle() {
+  local value="\${WPMOO_ALLOW_STAGE_LIFECYCLE:-$(env_file_value WPMOO_ALLOW_STAGE_LIFECYCLE)}"
+  [[ "$value" == "1" ]]
+}
+
+require_stage_lifecycle_allowed() {
+  local command="$1"
+  local env_name
+  env_name="$(selected_env)"
+  if [[ "$env_name" == "stage" ]]; then
+    if ! allow_stage_lifecycle; then
+      echo "Refusing stage lifecycle command '$command' in WPMOO_ENV=stage. Set WPMOO_ALLOW_STAGE_LIFECYCLE=1 to run it intentionally." >&2
+      exit 1
+    fi
+  fi
+}
+
 require_prod_lifecycle_allowed() {
   local command="$1"
   local env_name
@@ -676,12 +693,14 @@ case "$command" in
   "install")
     shift
     require_module_args "$command" "$@"
+    require_stage_lifecycle_allowed "$command"
     require_prod_lifecycle_allowed "$command"
     run_script ./scripts/install.sh "$@"
     ;;
   "update")
     shift
     require_module_args "$command" "$@"
+    require_stage_lifecycle_allowed "$command"
     require_prod_lifecycle_allowed "$command"
     run_script ./scripts/update.sh "$@"
     ;;
@@ -744,7 +763,7 @@ cd "$root_dir"
 
 node --input-type=module - "$@" <<'NODE'
 import { access, readdir, readFile, stat } from 'node:fs/promises';
-import { isAbsolute, join } from 'node:path';
+import { basename, isAbsolute, join, relative } from 'node:path';
 
 const args = process.argv.slice(2);
 if (!args.every((arg) => arg === '--json')) {
@@ -797,10 +816,100 @@ function normalizeSourceType(sourceType) {
   return typeof sourceType === 'string' && validSourceTypes.has(sourceType) ? sourceType : 'private';
 }
 
-async function countModuleCandidates(root) {
-  if (!(await isDirectory(root))) return 0;
+function emptyModuleQuality() {
+  return {
+    totalModules: 0,
+    installableModules: 0,
+    nonInstallableModules: 0,
+    modulesWithMenuActions: 0,
+    modulesMissingMenuActions: 0,
+    issues: [],
+  };
+}
+
+function manifestIsInstallable(content) {
+  return /["']installable["']\\s*:\\s*(?:True|true)\\b/.test(content);
+}
+
+function menuXmlHasAction(content, moduleName) {
+  const actionId = 'action_' + moduleName;
+  return (
+    content.includes('id="' + actionId + '"') &&
+    content.includes('model="ir.actions.act_window"') &&
+    content.includes('action="' + actionId + '"')
+  );
+}
+
+async function readMenuXmlFiles(modulePath) {
+  try {
+    const entries = await readdir(join(modulePath, 'views'), { withFileTypes: true });
+    return Promise.all(
+      entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('_menus.xml'))
+        .map((entry) => readFile(join(modulePath, 'views', entry.name), 'utf8')),
+    );
+  } catch {
+    return [];
+  }
+}
+
+async function analyzeModule(modulePath) {
+  const moduleName = basename(modulePath);
+  const moduleRelativePath = relative(target, modulePath);
+  const issues = [];
+  let installable = false;
+  try {
+    installable = manifestIsInstallable(await readFile(join(modulePath, '__manifest__.py'), 'utf8'));
+  } catch {
+    installable = false;
+  }
+  if (!installable) {
+    issues.push({
+      moduleName,
+      path: moduleRelativePath,
+      issue: 'missing installable=True in __manifest__.py',
+    });
+  }
+
+  const menuXml = await readMenuXmlFiles(modulePath);
+  const hasMenuAction = menuXml.some((content) => menuXmlHasAction(content, moduleName));
+  if (!hasMenuAction) {
+    issues.push({
+      moduleName,
+      path: moduleRelativePath,
+      issue: 'missing actionable menu XML',
+    });
+  }
+
+  return { installable, hasMenuAction, issues };
+}
+
+function addModuleQuality(summary, result) {
+  return {
+    totalModules: summary.totalModules + 1,
+    installableModules: summary.installableModules + (result.installable ? 1 : 0),
+    nonInstallableModules: summary.nonInstallableModules + (result.installable ? 0 : 1),
+    modulesWithMenuActions: summary.modulesWithMenuActions + (result.hasMenuAction ? 1 : 0),
+    modulesMissingMenuActions: summary.modulesMissingMenuActions + (result.hasMenuAction ? 0 : 1),
+    issues: [...summary.issues, ...result.issues],
+  };
+}
+
+function mergeModuleQuality(left, right) {
+  return {
+    totalModules: left.totalModules + right.totalModules,
+    installableModules: left.installableModules + right.installableModules,
+    nonInstallableModules: left.nonInstallableModules + right.nonInstallableModules,
+    modulesWithMenuActions: left.modulesWithMenuActions + right.modulesWithMenuActions,
+    modulesMissingMenuActions: left.modulesMissingMenuActions + right.modulesMissingMenuActions,
+    issues: [...left.issues, ...right.issues],
+  };
+}
+
+async function scanModuleQuality(root) {
+  if (!(await isDirectory(root))) return emptyModuleQuality();
   const stack = [root];
-  let count = 0;
+  let summary = emptyModuleQuality();
 
   while (stack.length > 0) {
     const current = stack.pop();
@@ -815,10 +924,12 @@ async function countModuleCandidates(root) {
       }
     }
 
-    if (hasManifest) count += 1;
+    if (hasManifest) {
+      summary = addModuleQuality(summary, await analyzeModule(current));
+    }
   }
 
-  return count;
+  return summary;
 }
 
 function parseEnvContent(content) {
@@ -985,6 +1096,21 @@ function renderStatus(status) {
     lines.push('Invalid source repo paths: ' + status.invalidSourceRepoPaths.join(', '));
   }
   lines.push('Module candidates: ' + status.moduleCandidateCount);
+  lines.push(
+    'Module quality: ' +
+      status.moduleQuality.installableModules +
+      ' installable, ' +
+      status.moduleQuality.nonInstallableModules +
+      ' non-installable, ' +
+      status.moduleQuality.modulesMissingMenuActions +
+      ' missing menu actions.',
+  );
+  if (status.moduleQuality.issues.length > 0) {
+    lines.push(
+      'Module quality issues: ' +
+        status.moduleQuality.issues.map((issue) => issue.path + ': ' + issue.issue).join('; '),
+    );
+  }
   lines.push('Missing core files: ' + (status.missingCoreFiles.length > 0 ? status.missingCoreFiles.join(', ') : '(none)'));
   lines.push('Next: ' + status.recommendedNextAction);
   return lines.join('\\n');
@@ -1033,10 +1159,14 @@ async function getStatus() {
     sourceRepoLocations.push({ sourceType, path });
   }
 
-  let moduleCandidateCount = 0;
+  let moduleQuality = emptyModuleQuality();
   for (const repo of sourceRepoLocations) {
-    moduleCandidateCount += await countModuleCandidates(join(target, 'odoo/custom/src', repo.sourceType, repo.path));
+    moduleQuality = mergeModuleQuality(
+      moduleQuality,
+      await scanModuleQuality(join(target, 'odoo/custom/src', repo.sourceType, repo.path)),
+    );
   }
+  const moduleCandidateCount = moduleQuality.totalModules;
 
   const { missing, composeFiles, composeErrors } = await coreFileIssues(odooVersion);
   let recommendedNextAction = 'Run ./moo doctor for deep checks or ./moo start.';
@@ -1059,6 +1189,7 @@ async function getStatus() {
     sourceRepoPaths,
     invalidSourceRepoPaths,
     moduleCandidateCount,
+    moduleQuality,
     composeFiles,
     composeErrors,
     missingCoreFiles: missing,

package/docs/handoff.md

@@ -23,6 +23,27 @@ Publishing is handled by the `Publish` GitHub Actions workflow through npm
 Trusted Publishing after the tag is pushed. Do not run `npm publish` manually
 unless a coordinator explicitly requests a fallback.
 
+Required release artifacts:
+
+- `@wpmoo/toolkit`
+- `@wpmoo/odoo`
+- `@wpmoo/odoo-dev`
+
+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.
+
+Verify a tagged release with:
+
+```bash
+npm view "@wpmoo/toolkit@$VERSION" version
+npm view "@wpmoo/odoo@$VERSION" version
+npm view "@wpmoo/odoo-dev@$VERSION" version
+```
+
+`npm view "wpmoo@$VERSION" version` is optional and may report that the short
+alias is absent.
+
 Current command standard:
 
 - Use `npx @wpmoo/toolkit ...` for package/operator commands.

package/package.json

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