@wpmoo/toolkit 0.9.8 → 0.9.10

package/README.md

@@ -58,15 +58,20 @@ Run the guided wizard from the workspace where you keep Odoo projects:
 npx @wpmoo/toolkit
 ```
 
-Short aliases are also available:
+Short alias:
 
 ```bash
 npx wpmoo
+```
+
+Deprecated compatibility aliases:
+
+```bash
 npx @wpmoo/odoo
 npx @wpmoo/odoo-dev
 ```
 
-Legacy package paths `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev` remain available for compatibility.
+Deprecated package paths `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev` remain available as compatibility aliases that redirect to `@wpmoo/toolkit`.
 
 When the current directory is not already a WPMoo environment, the CLI opens the create flow. It asks for a product slug, Odoo version, and environment folder. The default environment folder is `./<product>_dev`.
 
@@ -139,6 +144,10 @@ 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=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.
+
 Module source actions also have direct commands. Default is `private`; pass `--source-type oca` or `--source-type external` for non-private source repositories:
 
 ```bash
@@ -146,6 +155,8 @@ 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.
+
 For automation and VS Code cockpit integration, selected commands support JSON output:
 
 ```bash
@@ -153,9 +164,17 @@ npx @wpmoo/toolkit status --json
 npx @wpmoo/toolkit source list --json
 npx @wpmoo/toolkit source sync --json
 npx @wpmoo/toolkit doctor --json
+npx @wpmoo/toolkit doctor --postgres
+npx @wpmoo/toolkit doctor --json --postgres
 ```
 
 JSON output is optional; human-readable output remains the default.
+`doctor --postgres` adds read-only PostgreSQL health and performance diagnostics
+such as database size, sessions currently running queries with
+`pg_stat_activity.state = 'active'`, slow-query readiness, extension visibility,
+and settings.
+`doctor --json --postgres` includes a structured `postgres` object for automation.
+Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
 ## Documentation
 

package/dist/cli.js

@@ -42,6 +42,7 @@ import { environmentStatusJson, getEnvironmentStatus, renderEnvironmentStatusFor
 import { getGitHubAccounts, getGitHubRepositoryStatus, githubRepositoryUrl, realGitHub, createGitHubRepository, } from './github.js';
 import { environmentGitHubOwner } from './environment-context.js';
 import { handlePromptCancel, handleUnavailableMenuChoice, installPromptCancelKeyTracker, isMenuBackSignal, MenuBackSignal, menuIntroTitle, menuPromptMessage, } from './menu-navigation.js';
+import { validateModuleName } from './path-validation.js';
 function handleCancel(value, action) {
     handlePromptCancel(isPromptCancel(value), action);
 }
@@ -635,6 +636,15 @@ async function selectSourceRepo(target, cancelAction = 'exit') {
 function suggestedModuleName(repoPath) {
     return 'odoo_sample_module';
 }
+function validateModuleNameInput(value) {
+    try {
+        validateModuleName(value);
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : 'Invalid module name.';
+    }
+}
 async function addModuleOptionsFromArgs(argv) {
     const { values } = parseArgs(argv);
     const repoPath = stringOption(values, 'repo') ?? stringOption(values, 'sourcePath');
@@ -659,7 +669,7 @@ async function addModuleOptionsFromPrompts(showIntro = true, cancelAction = 'exi
     const moduleName = asString(await textPrompt({
         message: menuPromptMessage('Module name', cancelAction),
         placeholder: suggestedModuleName(sourceRepo.repoPath),
-        validate: (value) => (value.trim() ? undefined : 'Enter the module technical name.'),
+        validate: validateModuleNameInput,
     }), suggestedModuleName(sourceRepo.repoPath), cancelAction);
     return {
         target,
@@ -694,7 +704,7 @@ function resetCommandOptionsFromArgs(argv) {
 function doctorOptionsFromArgs(argv) {
     const { values } = parseArgs(argv);
     const keys = Object.keys(values);
-    const allowedKeys = new Set(['fix', 'json']);
+    const allowedKeys = new Set(['fix', 'json', 'postgres']);
     if (!keys.every((key) => allowedKeys.has(key))) {
         throw new Error('Usage: wpmoo doctor');
     }
@@ -704,6 +714,9 @@ function doctorOptionsFromArgs(argv) {
     if (Object.hasOwn(values, 'fix')) {
         options.fix = booleanOption(values, 'fix', false);
     }
+    if (Object.hasOwn(values, 'postgres')) {
+        options.postgres = booleanOption(values, 'postgres', false);
+    }
     return options;
 }
 function sourceUsage() {
@@ -1554,12 +1567,17 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
         if (options.fix !== undefined) {
             doctorOptions.fix = options.fix;
         }
+        if (options.postgres !== undefined) {
+            doctorOptions.postgres = options.postgres;
+        }
         if (options.json) {
             printJson(await getDoctorReport(cwd, doctorOptions));
             return;
         }
         console.log(renderBanner());
-        console.log(options.fix === undefined ? await runDoctor(cwd) : await runDoctor(cwd, doctorOptions));
+        console.log(options.fix === undefined && options.postgres === undefined
+            ? await runDoctor(cwd)
+            : await runDoctor(cwd, doctorOptions));
         return;
     }
     if (route.command === 'status') {

package/dist/daily-actions.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { readEnvFile, selectedComposeEnvironment } from './compose-layout.js';
 import { markerPath } from './environment.js';
 export const dailyActionCommands = [
     'start',
@@ -149,6 +150,48 @@ function scriptArgs(command, argv) {
         return ensureNoArgs(command, argv);
     return positionalArgs(command, argv, 1, 3);
 }
+function isDestructiveCommand(command, args) {
+    if (command === 'resetdb')
+        return true;
+    return command === 'restore-snapshot' && args[0] !== '--dry-run';
+}
+function isProductionLifecycleCommand(command) {
+    return command === 'install' || command === 'update' || command === 'test';
+}
+function destructiveCommandError(command, envName) {
+    return `Refusing destructive command '${command}' in WPMOO_ENV=${envName}. Set WPMOO_ALLOW_DESTRUCTIVE=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.`;
+}
+async function assertDestructiveCommandAllowed(command, args, cwd) {
+    if (!isDestructiveCommand(command, args)) {
+        return;
+    }
+    const env = await readEnvFile(cwd);
+    const envName = process.env.WPMOO_ENV?.trim() || selectedComposeEnvironment(env);
+    if (envName !== 'stage' && envName !== 'prod') {
+        return;
+    }
+    const allowDestructive = process.env.WPMOO_ALLOW_DESTRUCTIVE?.trim() || env?.get('WPMOO_ALLOW_DESTRUCTIVE')?.trim();
+    if (allowDestructive !== '1') {
+        throw new Error(destructiveCommandError(command, envName));
+    }
+}
+async function assertProductionLifecycleCommandAllowed(command, cwd) {
+    if (!isProductionLifecycleCommand(command)) {
+        return;
+    }
+    const env = await readEnvFile(cwd);
+    const envName = process.env.WPMOO_ENV?.trim() || selectedComposeEnvironment(env);
+    if (envName !== 'prod') {
+        return;
+    }
+    const allowProdLifecycle = process.env.WPMOO_ALLOW_PROD_LIFECYCLE?.trim() || env?.get('WPMOO_ALLOW_PROD_LIFECYCLE')?.trim();
+    if (allowProdLifecycle !== '1') {
+        throw new Error(productionLifecycleCommandError(command));
+    }
+}
 async function assertEnvironmentRoot(cwd) {
     try {
         await access(join(cwd, markerPath));
@@ -170,10 +213,13 @@ async function assertScriptExists(cwd, script) {
 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 assertProductionLifecycleCommandAllowed(command, cwd);
+    await assertDestructiveCommandAllowed(command, args, cwd);
     return {
         cwd,
         scriptPath,
-        args: scriptArgs(command, argv),
+        args,
     };
 }
 async function spawnDailyAction(plan) {

package/dist/doctor.js

@@ -46,6 +46,58 @@ function isMetadataError(message) {
         message.startsWith('Invalid sourceRepos entry in .wpmoo/odoo.json'));
 }
 const incompatiblePostgres18MountTargets = ['/var/lib/postgresql/data', '/var/lib/postgresql/18/docker'];
+const postgresDiagnosticQuery = `
+WITH metrics(metric, value) AS (
+  SELECT 'database_count', count(*)::text
+    FROM pg_database
+    WHERE datistemplate = false
+  UNION ALL
+  SELECT 'active_connections', count(*)::text
+    FROM pg_stat_activity
+    WHERE datname IS NOT NULL
+      AND state = 'active'
+  UNION ALL
+  SELECT 'total_database_size_bytes', COALESCE(sum(pg_database_size(datname)), 0)::text
+    FROM pg_database
+    WHERE datistemplate = false
+  UNION ALL
+  SELECT 'slow_query_logging', COALESCE(
+    (SELECT setting || unit FROM pg_settings WHERE name = 'log_min_duration_statement'),
+    'unavailable'
+  )
+  UNION ALL
+  SELECT 'pg_stat_statements',
+    CASE
+      WHEN EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements') THEN 'installed'
+      WHEN EXISTS (SELECT 1 FROM pg_available_extensions WHERE name = 'pg_stat_statements') THEN 'available'
+      ELSE 'unavailable'
+    END
+  UNION ALL
+  SELECT 'shared_buffers', COALESCE(
+    (SELECT setting FROM pg_settings WHERE name = 'shared_buffers'),
+    'unavailable'
+  )
+)
+SELECT metric || '|' || value
+FROM metrics
+ORDER BY CASE metric
+  WHEN 'database_count' THEN 1
+  WHEN 'active_connections' THEN 2
+  WHEN 'total_database_size_bytes' THEN 3
+  WHEN 'slow_query_logging' THEN 4
+  WHEN 'pg_stat_statements' THEN 5
+  WHEN 'shared_buffers' THEN 6
+  ELSE 99
+END;
+`.trim();
+const postgresDiagnosticKeys = [
+    'database_count',
+    'active_connections',
+    'total_database_size_bytes',
+    'slow_query_logging',
+    'pg_stat_statements',
+    'shared_buffers',
+];
 function parsePostgresMajorFromValue(value) {
     if (!value)
         return undefined;
@@ -56,6 +108,82 @@ function parsePostgresMajorFromValue(value) {
     const match = trimmed.match(/postgres:([0-9]{1,3})(?:[-._][A-Za-z0-9._-]+)?(?:@[\w:.-]+)?/i);
     return match?.[1];
 }
+function parsePostgresDiagnostics(output) {
+    const diagnostics = {};
+    const allowedKeys = new Set(postgresDiagnosticKeys);
+    for (const rawLine of output.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        const separatorIndex = line.indexOf('|');
+        if (separatorIndex === -1)
+            continue;
+        const key = line.slice(0, separatorIndex).trim();
+        const value = line.slice(separatorIndex + 1).trim();
+        if (allowedKeys.has(key) && value) {
+            diagnostics[key] = value;
+        }
+    }
+    return diagnostics;
+}
+function renderPostgresDiagnostics(diagnostics) {
+    const parts = postgresDiagnosticKeys.flatMap((key) => {
+        const value = diagnostics[key];
+        return value ? [`${key}=${value}`] : [];
+    });
+    return parts.length > 0 ? `OK PostgreSQL diagnostics ${parts.join(' ')}` : undefined;
+}
+function missingPostgresDiagnosticKeys(diagnostics) {
+    return postgresDiagnosticKeys.filter((key) => !diagnostics[key]);
+}
+function unavailablePostgresDiagnosticsWarning(diagnostics, missingKeys) {
+    return Object.keys(diagnostics).length === 0
+        ? 'no diagnostic rows returned'
+        : `incomplete diagnostic rows: missing ${missingKeys.join(', ')}`;
+}
+function integerDiagnostic(value) {
+    if (!value || !/^\d+$/u.test(value)) {
+        return undefined;
+    }
+    return Number.parseInt(value, 10);
+}
+function malformedPostgresDiagnosticKeys(diagnostics) {
+    const numericKeys = [
+        'database_count',
+        'active_connections',
+        'total_database_size_bytes',
+    ];
+    return numericKeys.filter((key) => diagnostics[key] !== undefined && integerDiagnostic(diagnostics[key]) === undefined);
+}
+function structuredPostgresDiagnostics(diagnostics) {
+    const structured = {};
+    const databaseCount = integerDiagnostic(diagnostics.database_count);
+    const activeConnections = integerDiagnostic(diagnostics.active_connections);
+    const totalDatabaseSizeBytes = integerDiagnostic(diagnostics.total_database_size_bytes);
+    if (databaseCount !== undefined)
+        structured.databaseCount = databaseCount;
+    if (activeConnections !== undefined)
+        structured.activeConnections = activeConnections;
+    if (totalDatabaseSizeBytes !== undefined)
+        structured.totalDatabaseSizeBytes = totalDatabaseSizeBytes;
+    if (diagnostics.slow_query_logging)
+        structured.slowQueryLogging = diagnostics.slow_query_logging;
+    if (diagnostics.pg_stat_statements)
+        structured.pgStatStatements = diagnostics.pg_stat_statements;
+    if (diagnostics.shared_buffers)
+        structured.sharedBuffers = diagnostics.shared_buffers;
+    return structured;
+}
+async function readPostgresDiagnostics(target, runner) {
+    const queryLiteral = JSON.stringify(postgresDiagnosticQuery);
+    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 });
+    return parsePostgresDiagnostics(result.stdout);
+}
 function stripInlineComment(line) {
     const hashIndex = line.indexOf('#');
     if (hashIndex === -1)
@@ -441,6 +569,46 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
             checks.push(`OK .env ports HTTP_PORT=${httpPort} GEVENT_PORT=${geventPort}`);
         }
     }
+    if (actualOptions.postgres) {
+        try {
+            const postgresDiagnostics = await readPostgresDiagnostics(target, actualRunner);
+            const missingKeys = missingPostgresDiagnosticKeys(postgresDiagnostics);
+            const malformedKeys = malformedPostgresDiagnosticKeys(postgresDiagnostics);
+            if (missingKeys.length === 0 && malformedKeys.length === 0) {
+                const renderedPostgresDiagnostics = renderPostgresDiagnostics(postgresDiagnostics);
+                if (renderedPostgresDiagnostics) {
+                    checks.push(renderedPostgresDiagnostics);
+                }
+                report.postgres = {
+                    requested: true,
+                    available: true,
+                    diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
+                };
+            }
+            else {
+                const warning = malformedKeys.length > 0
+                    ? `malformed diagnostic values: ${malformedKeys.join(', ')}`
+                    : unavailablePostgresDiagnosticsWarning(postgresDiagnostics, missingKeys);
+                warnings.push(`PostgreSQL diagnostics unavailable: ${warning}`);
+                report.postgres = {
+                    requested: true,
+                    available: false,
+                    diagnostics: structuredPostgresDiagnostics(postgresDiagnostics),
+                    warning,
+                };
+            }
+        }
+        catch (error) {
+            const warning = errorMessage(error);
+            warnings.push(`PostgreSQL diagnostics unavailable: ${warning}`);
+            report.postgres = {
+                requested: true,
+                available: false,
+                diagnostics: {},
+                warning,
+            };
+        }
+    }
     try {
         await actualRunner('docker', ['version'], { cwd: target });
         checks.push('OK docker CLI');

package/dist/external-templates.js

@@ -43,6 +43,8 @@ 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.',
+        '# WPMOO_ALLOW_PROD_LIFECYCLE=1',
         '',
     ].join('\n');
 }

package/dist/help.js

@@ -20,8 +20,8 @@ Usage:
   npx @wpmoo/toolkit add-module --repo <source-repo> --module <module-name> [--source-type <category>]
   npx @wpmoo/toolkit remove-module --repo <source-repo> --module <module-name> [--source-type <category>]
   npx @wpmoo/toolkit reset [--dry-run]
-  npx @wpmoo/toolkit doctor [--fix]
-  npx @wpmoo/toolkit doctor --json
+  npx @wpmoo/toolkit doctor [--fix] [--postgres]
+  npx @wpmoo/toolkit doctor --json [--postgres]
   npx @wpmoo/toolkit start
   npx @wpmoo/toolkit stop
   npx @wpmoo/toolkit logs [service]
@@ -58,6 +58,7 @@ Options:
   --source-type <category>     Source repo category for add-repo/remove-repo/add-module/remove-module. One of private, oca, external. Default: private.
   --repo <name>                Source repo folder name for repo/module actions.
   --module <name>              Odoo module technical name for module actions.
+                               Must be lower snake_case; use letters, numbers, and underscores only.
   --delete-files               Also delete module files in remove-module. Default: false.
   --odoo-version <branch>      Override the environment Odoo branch for add-repo/add-module.
   --source-repo-url <url>      Source repo URL. Repeat for multiple repos.
@@ -67,6 +68,7 @@ Options:
   --repo-visibility <value>    Visibility for created repos: private or public. Default: private.
   --init-empty-repos           Initialize empty source repos with the selected branch.
   --dry-run                    Print planned files and commands without writing.
+  --postgres                   Include read-only PostgreSQL health/performance diagnostics in doctor.
   --stage=false                Do not run git add .
   --no-update-check            Skip the startup npm update check.
   --version, -v                Show the package version.
@@ -75,7 +77,7 @@ Options:
 Package aliases:
   npx @wpmoo/toolkit is the official package path.
   npx wpmoo is the short alias.
-  npx @wpmoo/odoo and npx @wpmoo/odoo-dev remain legacy compatibility paths.
+  npx @wpmoo/odoo and npx @wpmoo/odoo-dev remain deprecated compatibility aliases.
 
 Daily actions:
   Daily actions must be run from a generated environment root containing .wpmoo/odoo.json.
@@ -83,6 +85,11 @@ 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:
+  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.
+
 Cockpit:
   Run npx @wpmoo/toolkit inside a generated environment to open the cockpit.
   Use Command palette / to search slash commands across services, modules, database,
@@ -101,6 +108,10 @@ 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.
+  doctor --postgres: adds read-only PostgreSQL diagnostics such as database size,
+    sessions currently running queries with pg_stat_activity.state = 'active',
+    slow-query readiness, extension visibility, and settings.
+    Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
 Task recipes:
   Create environment:
@@ -115,6 +126,9 @@ Task recipes:
     npx @wpmoo/toolkit source sync
   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.
+    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
   Add OCA module:
@@ -140,6 +154,8 @@ Machine-readable JSON output:
     npx @wpmoo/toolkit source list --json
     npx @wpmoo/toolkit source sync --json
     npx @wpmoo/toolkit doctor --json
+    doctor --json --postgres includes a structured postgres object for automation.
+    Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
 Example:
   npx @wpmoo/toolkit create \\

package/dist/module-actions.js

@@ -1,11 +1,12 @@
 import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { addModuleToSourceRepoInAddonsYaml, removeModuleFromSourceRepoInAddonsYaml, } from './addons-yaml.js';
-import { readEnvironmentMetadata } from './environment.js';
+import { readEnvironmentMetadata, replaceSourceRepos } from './environment.js';
 import { realGit, stageAll } from './git.js';
 import { pathUnderBase, validateModuleName, validateRepoPath } from './path-validation.js';
 import { listModuleRepos, readAddonsYaml, writeAddonsYaml } from './repo-actions.js';
 import { listSources } from './source-actions.js';
+import { readSourceManifest, writeSourceManifest } from './source-manifest.js';
 const sourceTypeSortOrder = ['private', 'oca', 'external'];
 const githubRepoUrlPattern = /^(?:https?:\/\/|git@)github\.com[/:]([^/]+)\/([^/.#?]+)(?:\.git)?(?:[/?#].*)?$/i;
 const validSourceTypes = ['private', 'oca', 'external'];
@@ -41,15 +42,45 @@ function titleizeModule(moduleName) {
         .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
         .join(' ');
 }
+function moduleClassName(moduleName) {
+    const className = titleizeModule(moduleName).replace(/[^A-Za-z0-9]/g, '');
+    return /^[A-Za-z_]/.test(className) ? className : `X${className}`;
+}
+function modelTechnicalName(moduleName) {
+    return moduleName.replace(/[_-]+/g, '.').toLowerCase();
+}
+function actionViewMode(odooVersion) {
+    const majorVersion = Number.parseInt(odooVersion.split('.', 1)[0] ?? '', 10);
+    return Number.isFinite(majorVersion) && majorVersion < 18 ? 'tree,form' : 'list,form';
+}
+function listViewTag(odooVersion) {
+    const majorVersion = Number.parseInt(odooVersion.split('.', 1)[0] ?? '', 10);
+    return Number.isFinite(majorVersion) && majorVersion < 18 ? 'tree' : 'list';
+}
+function modelContent(moduleName) {
+    const moduleTitle = titleizeModule(moduleName);
+    return `from odoo import fields, models
+
+
+class ${moduleClassName(moduleName)}(models.Model):
+    _name = "${modelTechnicalName(moduleName)}"
+    _description = "${moduleTitle}"
+
+    name = fields.Char(required=True, default="New")
+`;
+}
 function manifestContent(moduleName, odooVersion) {
+    const moduleTitle = titleizeModule(moduleName);
     return `{
-    "name": "${titleizeModule(moduleName)}",
+    "name": "${moduleTitle}",
     "version": "${odooVersion}.1.0.0",
     "category": "Productivity",
-    "summary": "TODO",
+    "summary": "${moduleTitle} module",
     "depends": ["base"],
     "data": [
         "security/ir.model.access.csv",
+        "views/${moduleName}_views.xml",
+        "views/${moduleName}_menus.xml",
     ],
     "installable": True,
     "application": False,
@@ -57,6 +88,78 @@ function manifestContent(moduleName, odooVersion) {
 }
 `;
 }
+function viewXmlContent(moduleName, odooVersion) {
+    const moduleTitle = titleizeModule(moduleName);
+    const technicalName = modelTechnicalName(moduleName);
+    const primaryViewTag = listViewTag(odooVersion);
+    return `<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+    <record id="view_${moduleName}_${primaryViewTag}" model="ir.ui.view">
+        <field name="name">${technicalName}.${primaryViewTag}</field>
+        <field name="model">${technicalName}</field>
+        <field name="arch" type="xml">
+            <${primaryViewTag} string="${moduleTitle}">
+                <field name="name"/>
+            </${primaryViewTag}>
+        </field>
+    </record>
+
+    <record id="view_${moduleName}_form" model="ir.ui.view">
+        <field name="name">${technicalName}.form</field>
+        <field name="model">${technicalName}</field>
+        <field name="arch" type="xml">
+            <form string="${moduleTitle}">
+                <sheet>
+                    <group>
+                        <field name="name"/>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+</odoo>
+`;
+}
+function menuXmlContent(moduleName, odooVersion) {
+    const moduleTitle = titleizeModule(moduleName);
+    return `<?xml version="1.0" encoding="utf-8"?>
+<odoo>
+    <record id="action_${moduleName}" model="ir.actions.act_window">
+        <field name="name">${moduleTitle}</field>
+        <field name="res_model">${modelTechnicalName(moduleName)}</field>
+        <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"/>
+</odoo>
+`;
+}
+function accessCsvContent(moduleName) {
+    const modelId = modelTechnicalName(moduleName).replace(/\./g, '_');
+    return [
+        'id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink',
+        `access_${modelId}_user,access_${modelId}_user,model_${modelId},base.group_user,1,1,1,1`,
+        '',
+    ].join('\n');
+}
+function testInitContent(moduleName) {
+    return `from . import test_${moduleName}\n`;
+}
+function testContent(moduleName) {
+    const moduleTitle = titleizeModule(moduleName);
+    return `from odoo.tests import tagged
+from odoo.tests.common import TransactionCase
+
+
+@tagged("post_install", "-at_install")
+class Test${moduleClassName(moduleName)}(TransactionCase):
+
+    def test_create_record(self):
+        record = self.env["${modelTechnicalName(moduleName)}"].create({"name": "Test ${moduleTitle}"})
+        self.assertEqual(record.name, "Test ${moduleTitle}")
+`;
+}
 async function writeIfMissing(path, content) {
     try {
         await readFile(path, 'utf8');
@@ -69,6 +172,59 @@ async function usesAddonsYaml(target) {
     const metadata = await readEnvironmentMetadata(target);
     return metadata?.engine !== 'compose';
 }
+function updateAddonList(addons, moduleName, mode) {
+    if (mode === 'add') {
+        return [...new Set([...addons, moduleName])];
+    }
+    return addons.filter((addon) => addon !== moduleName);
+}
+function addonListsEqual(left, right) {
+    return left.length === right.length && left.every((addon, index) => addon === right[index]);
+}
+async function updateSourceManifestModuleRegistration(target, sourceType, repoPath, moduleName, mode) {
+    const manifest = await readSourceManifest(target);
+    if (manifest.sources.length === 0) {
+        return;
+    }
+    let changed = false;
+    const sources = manifest.sources.map((entry) => {
+        if (entry.type !== sourceType || entry.path !== repoPath) {
+            return entry;
+        }
+        const addons = updateAddonList(entry.addons, moduleName, mode);
+        if (!addonListsEqual(entry.addons, addons)) {
+            changed = true;
+        }
+        return { ...entry, addons };
+    });
+    if (changed) {
+        await writeSourceManifest(target, sources);
+    }
+}
+async function updateMetadataModuleRegistration(target, sourceType, repoPath, moduleName, mode) {
+    const metadata = await readEnvironmentMetadata(target);
+    if (!metadata?.sourceRepos?.length) {
+        return;
+    }
+    let changed = false;
+    const sourceRepos = metadata.sourceRepos.map((repo) => {
+        if (normalizeSourceType(repo.sourceType) !== sourceType || repo.path !== repoPath) {
+            return repo;
+        }
+        const addons = updateAddonList(repo.addons, moduleName, mode);
+        if (!addonListsEqual(repo.addons, addons)) {
+            changed = true;
+        }
+        return { ...repo, addons };
+    });
+    if (changed) {
+        await replaceSourceRepos(target, sourceRepos);
+    }
+}
+async function updateModuleRegistration(target, sourceType, repoPath, moduleName, mode) {
+    await updateSourceManifestModuleRegistration(target, sourceType, repoPath, moduleName, mode);
+    await updateMetadataModuleRegistration(target, sourceType, repoPath, moduleName, mode);
+}
 export async function addModuleToSourceRepo(options, git = realGit) {
     const repoPath = validateRepoPath(options.repoPath);
     const moduleName = validateModuleName(options.moduleName);
@@ -76,16 +232,23 @@ export async function addModuleToSourceRepo(options, git = realGit) {
     const destination = modulePath(options.target, sourceType, repoPath, moduleName);
     await mkdir(join(destination, 'models'), { recursive: true });
     await mkdir(join(destination, 'security'), { recursive: true });
+    await mkdir(join(destination, 'tests'), { recursive: true });
     await mkdir(join(destination, 'views'), { recursive: true });
     await writeIfMissing(join(destination, '__init__.py'), 'from . import models\n');
     await writeIfMissing(join(destination, '__manifest__.py'), manifestContent(moduleName, options.odooVersion));
-    await writeIfMissing(join(destination, 'models/__init__.py'), '');
-    await writeIfMissing(join(destination, 'security/ir.model.access.csv'), 'id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink\n');
+    await writeIfMissing(join(destination, 'models/__init__.py'), `from . import ${moduleName}\n`);
+    await writeIfMissing(join(destination, `models/${moduleName}.py`), modelContent(moduleName));
+    await writeIfMissing(join(destination, 'tests/__init__.py'), testInitContent(moduleName));
+    await writeIfMissing(join(destination, `tests/test_${moduleName}.py`), testContent(moduleName));
+    await writeIfMissing(join(destination, 'security/ir.model.access.csv'), accessCsvContent(moduleName));
+    await writeIfMissing(join(destination, `views/${moduleName}_views.xml`), viewXmlContent(moduleName, options.odooVersion));
+    await writeIfMissing(join(destination, `views/${moduleName}_menus.xml`), menuXmlContent(moduleName, options.odooVersion));
     await writeIfMissing(join(destination, 'views/.gitkeep'), '');
     if (sourceType === 'private' && (await usesAddonsYaml(options.target))) {
         const addonsYaml = await readAddonsYaml(options.target);
         await writeAddonsYaml(options.target, addModuleToSourceRepoInAddonsYaml(addonsYaml, repoPath, moduleName));
     }
+    await updateModuleRegistration(options.target, sourceType, repoPath, moduleName, 'add');
     if (options.stage) {
         await stageAll(git, sourceRepoPath(options.target, sourceType, repoPath));
         await stageAll(git, options.target);
@@ -151,6 +314,7 @@ export async function removeModuleFromSourceRepo(options, git = realGit) {
         const addonsYaml = await readAddonsYaml(options.target);
         await writeAddonsYaml(options.target, removeModuleFromSourceRepoInAddonsYaml(addonsYaml, repoPath, moduleName));
     }
+    await updateModuleRegistration(options.target, sourceType, repoPath, moduleName, 'remove');
     if (options.deleteFiles) {
         await rm(modulePath(options.target, sourceType, repoPath, moduleName), { recursive: true, force: true });
     }

package/dist/path-validation.js

@@ -1,5 +1,6 @@
 import { isAbsolute, relative, resolve } from 'node:path';
 const windowsDrivePattern = /^[a-zA-Z]:/;
+const odooModuleNamePattern = /^[a-z][a-z0-9_]*$/;
 function invalidPathError(label) {
     return new Error(`Invalid ${label}: use a single path segment without traversal.`);
 }
@@ -33,7 +34,11 @@ export function validateRepoPath(value) {
     return validatePathSegment(value, 'repo path');
 }
 export function validateModuleName(value) {
-    return validatePathSegment(value, 'module name');
+    const moduleName = validatePathSegment(value, 'module name');
+    if (!odooModuleNamePattern.test(moduleName)) {
+        throw new Error('Invalid module name: use lower snake_case letters, numbers, and underscores, and start with a letter.');
+    }
+    return moduleName;
 }
 export function validateAddonName(value) {
     return validatePathSegment(value, 'addon name');

package/dist/source-manifest.js

@@ -100,6 +100,7 @@ function parseSourcesBlock(content) {
             url: '',
             addons: [],
         };
+        let hasAddonsField = false;
         index += 1;
         while (index < sourceLines.length) {
             const rawLine = sourceLines[index];
@@ -130,8 +131,14 @@ function parseSourcesBlock(content) {
                 index += 1;
                 continue;
             }
-            const addonsLine = /^\s*addons:\s*$/.exec(noComment);
-            if (addonsLine) {
+            const emptyAddonsLine = /^\s*addons:\s*\[\s*\]\s*$/.exec(noComment);
+            if (emptyAddonsLine) {
+                hasAddonsField = true;
+                index += 1;
+                continue;
+            }
+            if (/^\s*addons:\s*$/.test(noComment)) {
+                hasAddonsField = true;
                 const baseIndent = leadingSpaces(rawLine.line) + 2;
                 index += 1;
                 while (index < sourceLines.length) {
@@ -167,7 +174,7 @@ function parseSourcesBlock(content) {
         if (!isValidPathSegment(item.path)) {
             fail(`Invalid manifest path at line ${headerLine.lineNumber}: ${item.path}`);
         }
-        if (item.addons.length === 0) {
+        if (!hasAddonsField && item.addons.length === 0) {
             item.addons.push(item.path);
         }
         item.addons = [...new Set(item.addons.map((addon) => validateRepoPath(addon)))].sort();
@@ -198,7 +205,7 @@ export function renderSourceManifest(entries) {
             path: validateRepoPath(entry.path),
             url: entry.url.trim(),
             branch: entry.branch?.trim(),
-            addons: addons.length ? addons : [validateRepoPath(entry.path)],
+            addons,
         };
     });
     if (normalized.length === 0) {
@@ -212,9 +219,14 @@ export function renderSourceManifest(entries) {
             `    url: ${renderQuoted(entry.url)}`,
         ];
         lines.push(`    branch: ${renderQuoted(entry.branch ?? '')}`);
-        lines.push('    addons:');
-        for (const addon of entry.addons) {
-            lines.push(`      - ${renderQuoted(addon)}`);
+        if (entry.addons.length === 0) {
+            lines.push('    addons: []');
+        }
+        else {
+            lines.push('    addons:');
+            for (const addon of entry.addons) {
+                lines.push(`      - ${renderQuoted(addon)}`);
+            }
         }
         return lines.join('\n');
     })
@@ -333,6 +345,6 @@ export function sourceReposFromManifest(entries) {
         sourceType: entry.type,
         path: validateRepoPath(entry.path),
         url: entry.url,
-        addons: entry.addons.length ? [...new Set(entry.addons.map((addon) => validateRepoPath(addon)))] : [validateRepoPath(entry.path)],
+        addons: [...new Set(entry.addons.map((addon) => validateRepoPath(addon)))],
     }));
 }

package/dist/templates.js

@@ -208,6 +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
+resetdb and real restore-snapshot require WPMOO_ALLOW_DESTRUCTIVE=1 in stage
+and prod. restore-snapshot --dry-run remains available for preview.
 
 If copied from the standalone resource, additional compose notes are in
 \`docs/compose.md\`.
@@ -539,6 +543,52 @@ validate_test_args() {
   done
 }
 
+env_file_value() {
+  local key="$1"
+  if [[ -f ".env" ]]; then
+    grep -E "^[[:space:]]*\${key}[[:space:]]*=" ".env" | tail -n 1 | sed -E "s/^[[:space:]]*\${key}[[:space:]]*=[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^[\\"']//; s/[\\"']$//"
+  fi
+}
+
+selected_env() {
+  local value="\${WPMOO_ENV:-$(env_file_value WPMOO_ENV)}"
+  printf '%s\\n' "\${value:-dev}"
+}
+
+allow_destructive() {
+  local value="\${WPMOO_ALLOW_DESTRUCTIVE:-$(env_file_value WPMOO_ALLOW_DESTRUCTIVE)}"
+  [[ "$value" == "1" ]]
+}
+
+require_destructive_allowed() {
+  local command="$1"
+  local env_name
+  env_name="$(selected_env)"
+  if [[ "$env_name" == "stage" || "$env_name" == "prod" ]]; then
+    if ! allow_destructive; then
+      echo "Refusing destructive command '$command' in WPMOO_ENV=$env_name. Set WPMOO_ALLOW_DESTRUCTIVE=1 to run it intentionally." >&2
+      exit 1
+    fi
+  fi
+}
+
+allow_prod_lifecycle() {
+  local value="\${WPMOO_ALLOW_PROD_LIFECYCLE:-$(env_file_value WPMOO_ALLOW_PROD_LIFECYCLE)}"
+  [[ "$value" == "1" ]]
+}
+
+require_prod_lifecycle_allowed() {
+  local command="$1"
+  local env_name
+  env_name="$(selected_env)"
+  if [[ "$env_name" == "prod" ]]; then
+    if ! allow_prod_lifecycle; then
+      echo "Refusing production lifecycle command '$command' in WPMOO_ENV=prod. Set WPMOO_ALLOW_PROD_LIFECYCLE=1 to run it intentionally." >&2
+      exit 1
+    fi
+  fi
+}
+
 run_script() {
   local script="$1"
   shift
@@ -584,21 +634,25 @@ case "$command" in
   "install")
     shift
     require_module_args "$command" "$@"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/install.sh "$@"
     ;;
   "update")
     shift
     require_module_args "$command" "$@"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/update.sh "$@"
     ;;
   "test")
     shift
     validate_test_args "$@"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/test.sh "$@"
     ;;
   "resetdb")
     shift
     positional_args "$command" 0 2 "$@"
+    require_destructive_allowed "$command"
     run_script ./scripts/resetdb.sh "$@"
     ;;
   "snapshot")
@@ -615,6 +669,9 @@ case "$command" in
     fi
     positional_args "$command" 1 2 "$@"
     restore_args+=("$@")
+    if [[ "\${restore_args[0]:-}" != "--dry-run" ]]; then
+      require_destructive_allowed "$command"
+    fi
     run_script ./scripts/restore-snapshot.sh "\${restore_args[@]}"
     ;;
   "lint")

package/docs/generated-environment-verification.md

@@ -23,9 +23,10 @@ not validate staging or production deployments.
 | Doctor checks | Metadata, compose files, scripts, source repo paths, and local tooling checks behave as expected. | `npx @wpmoo/toolkit doctor` or `./moo doctor` |
 | Doctor safe fixes | Safe file-level fixes are applied only with `--fix`, then doctor runs again and reports any remaining manual issues. | `npx @wpmoo/toolkit doctor --fix` |
 | Generated Postgres checks | For PostgreSQL 18 environments, doctor validates db mount targets avoid old PG image-specific paths and can normalize safe targets with `--fix`. | `npx @wpmoo/toolkit doctor`, `npx @wpmoo/toolkit doctor --fix` |
+| PostgreSQL diagnostics | Optional read-only database health/performance diagnostics report database count, sessions currently running queries with `pg_stat_activity.state = 'active'`, total database size, slow-query readiness, extension visibility, and selected settings without failing doctor when the database is unavailable. | `npx @wpmoo/toolkit doctor --postgres`, `npx @wpmoo/toolkit doctor --json --postgres` |
 | Source repo add/remove | Source repository registration and submodule lifecycle behave correctly. | `npx @wpmoo/toolkit add-repo ...`, `npx @wpmoo/toolkit remove-repo ...` |
 | Source manifest sync | Source repo metadata, `.gitmodules`, and `odoo/custom/manifests/sources.yaml` stay aligned. | `npx @wpmoo/toolkit source list`, `npx @wpmoo/toolkit source sync` |
-| Module add/remove | Module registration changes are applied to the selected source repo config. | `npx @wpmoo/toolkit add-module ...`, `npx @wpmoo/toolkit remove-module ...` |
+| Module add/remove | Module skeleton files include manifest, model, access CSV, explicit view XML, action/menu XML, post-install test scaffold, and selected source repo registration. Existing scaffold files are not overwritten. | `npx @wpmoo/toolkit add-module ...`, `npx @wpmoo/toolkit remove-module ...` |
 | 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/toolkit reset --dry-run`, `npx @wpmoo/toolkit 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 ...` |
 
@@ -46,9 +47,17 @@ 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`.
+When `WPMOO_ENV=stage` or `WPMOO_ENV=prod`, WPMoo refuses destructive database
+actions such as `resetdb` and real `restore-snapshot` before dispatching local
+scripts unless `.env` or the process environment explicitly sets
+`WPMOO_ALLOW_DESTRUCTIVE=1`. `restore-snapshot --dry-run` remains allowed for
+safe preview.
+
+When `WPMOO_ENV=prod`, WPMoo also refuses module lifecycle commands that mutate
+or exercise the Odoo database (`install`, `update`, and `test`) unless `.env` or
+the process environment explicitly sets `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
+Staging keeps these commands available for release rehearsal while still
+enforcing the destructive database guard above.
 
 For PostgreSQL 18 environments (including `POSTGRES_IMAGE=postgres:18`), ensure db
 volume and tmpfs mount targets use `/var/lib/postgresql` directly:
@@ -65,6 +74,19 @@ no longer accepted by the package `doctor` check.
 It does not upgrade existing database data; if a real PostgreSQL major upgrade
 is involved, use PostgreSQL upgrade tooling first.
 
+Use `doctor --postgres` when the database container is running and you want
+read-only PostgreSQL diagnostics. The check uses fixed diagnostic queries for
+database count, sessions currently running queries where
+`pg_stat_activity.state` is `active`, aggregate database size, slow-query
+logging readiness,
+`pg_stat_statements` availability, and `shared_buffers`. If the database is
+unavailable, doctor reports a warning instead of failing the whole environment
+check.
+JSON output preserves `checks` and `warnings` while adding a structured
+`postgres` object when `--postgres` is requested.
+Incomplete or malformed PostgreSQL metric rows are reported as unavailable
+diagnostics.
+
 ## Safe reset policy
 
 Safe reset intentionally avoids deleting user-editable legacy paths from old

package/package.json

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