@wpmoo/toolkit 0.9.29 → 0.9.31

package/dist/databases.js

@@ -1,13 +1,128 @@
-import { readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import { spawn } from 'node:child_process';
 export const defaultDatabaseSnapshotMaxAgeMs = 24 * 60 * 60 * 1000;
-export const databaseSnapshotDirectoryNames = ['backups', 'backup', 'snapshots'];
+export const databaseSnapshotDirectoryNames = ['backups/snapshots', 'backups', 'backup', 'snapshots'];
 export const databaseSnapshotExtensions = ['.dump', '.sql', '.sql.gz', '.zip', '.tar', '.tar.gz'];
 function isDatabaseSnapshotFile(fileName, extensions) {
     const normalized = fileName.toLowerCase();
     return extensions.some((extension) => normalized.endsWith(extension));
 }
+function fileExists(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function stripSnapshotExtension(fileName) {
+    const normalized = fileName.toLowerCase();
+    const suffixes = ['.filestore.tar.gz', '.sql.gz', '.tar.gz', '.dump', '.sql', '.zip', '.tar', '.json'];
+    const suffix = suffixes.find((candidate) => normalized.endsWith(candidate));
+    return suffix ? fileName.slice(0, -suffix.length) : undefined;
+}
+function snapshotComponentKind(fileName, snapshotExtensions) {
+    const normalized = fileName.toLowerCase();
+    if (normalized.endsWith('.json'))
+        return 'manifest';
+    if (normalized.endsWith('.filestore.tar.gz'))
+        return 'filestore';
+    return isDatabaseSnapshotFile(fileName, snapshotExtensions) ? 'dump' : undefined;
+}
+function snapshotNameFromPath(path) {
+    return stripSnapshotExtension(basename(path));
+}
+function snapshotComponentPriority(component) {
+    const normalized = component.fileName.toLowerCase();
+    if (normalized.endsWith('.dump'))
+        return 0;
+    if (normalized.endsWith('.sql.gz'))
+        return 1;
+    if (normalized.endsWith('.sql'))
+        return 2;
+    return 3;
+}
+function readSnapshotManifest(path) {
+    if (!path)
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const defaultSnapshotDatabaseNameHints = ['devel', 'stage', 'staging', 'prod', 'production', 'test', 'postgres'];
+function inferDatabaseNameFromSnapshotName(snapshotName, databaseNames) {
+    const candidates = databaseNames?.length ? databaseNames : defaultSnapshotDatabaseNameHints;
+    const match = candidates
+        .filter(isValidDatabaseName)
+        .sort((left, right) => right.length - left.length)
+        .find((database) => snapshotName.startsWith(`${database}-`) || snapshotName.startsWith(`${database}.`) || snapshotName.startsWith(`${database}_`));
+    return match;
+}
+function manifestDateMs(manifest) {
+    if (!manifest || typeof manifest.created_at !== 'string')
+        return undefined;
+    const parsed = Date.parse(manifest.created_at);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function manifestDatabaseName(manifest) {
+    return typeof manifest?.database === 'string' && isValidDatabaseName(manifest.database) ? manifest.database : undefined;
+}
+function snapshotGroups(targetDirectory, snapshotDirectories, snapshotExtensions) {
+    const groups = new Map();
+    for (const directoryName of snapshotDirectories) {
+        const directory = join(targetDirectory, directoryName);
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                continue;
+            }
+            throw error;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile()) {
+                continue;
+            }
+            const stem = stripSnapshotExtension(entry.name);
+            const kind = snapshotComponentKind(entry.name, snapshotExtensions);
+            if (!stem || !kind) {
+                continue;
+            }
+            const path = join(directory, entry.name);
+            let stats;
+            try {
+                stats = statSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (!stats.isFile()) {
+                continue;
+            }
+            const key = `${directory}\0${stem}`;
+            const group = groups.get(key) ?? { directory, stem, dumps: [], filestores: [] };
+            const component = { path, fileName: entry.name, stem, kind, stats };
+            if (kind === 'manifest') {
+                group.manifest = component;
+            }
+            else if (kind === 'filestore') {
+                group.filestores.push(component);
+            }
+            else {
+                group.dumps.push(component);
+            }
+            groups.set(key, group);
+        }
+    }
+    return [...groups.values()];
+}
 const maintenanceDatabases = new Set(['postgres']);
 const databaseNamePattern = /^[A-Za-z0-9_.-]+$/u;
 export function isValidDatabaseName(value) {
@@ -33,6 +148,22 @@ export function normalizeDatabaseName(value) {
     }
     return normalized;
 }
+export function normalizeSnapshotName(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error('Invalid snapshot name: value is required.');
+    }
+    if (/\s/u.test(value)) {
+        throw new Error('Invalid snapshot name: whitespace is not allowed.');
+    }
+    if (normalized.startsWith('-')) {
+        throw new Error('Invalid snapshot name: leading hyphens are not allowed.');
+    }
+    if (!databaseNamePattern.test(normalized)) {
+        throw new Error('Invalid snapshot name: use letters, digits, underscores, dots, or hyphens without shell metacharacters or path characters.');
+    }
+    return normalized;
+}
 const listDatabasesQuery = [
     'SELECT datname',
     'FROM pg_database',
@@ -56,40 +187,35 @@ export function parseDatabaseListOutput(output, options = {}) {
     return databases;
 }
 export function findDatabaseSnapshots(targetDirectory, options = {}) {
-    const { nowMs = Date.now(), snapshotDirectories = [...databaseSnapshotDirectoryNames], snapshotExtensions = [...databaseSnapshotExtensions], } = options;
-    const snapshots = [];
-    for (const directoryName of snapshotDirectories) {
-        const directory = join(targetDirectory, directoryName);
-        let entries;
-        try {
-            entries = readdirSync(directory, { withFileTypes: true });
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                continue;
-            }
-            throw error;
+    const { nowMs = Date.now(), snapshotDirectories = [...databaseSnapshotDirectoryNames], snapshotExtensions = [...databaseSnapshotExtensions], snapshotDatabaseNames, } = options;
+    const snapshots = snapshotGroups(targetDirectory, snapshotDirectories, snapshotExtensions)
+        .flatMap((group) => {
+        const primary = [...group.dumps].sort((left, right) => snapshotComponentPriority(left) - snapshotComponentPriority(right) ||
+            right.stats.mtimeMs - left.stats.mtimeMs ||
+            left.path.localeCompare(right.path))[0];
+        if (!primary) {
+            return [];
         }
-        for (const entry of entries) {
-            if (!isDatabaseSnapshotFile(entry.name, snapshotExtensions)) {
-                continue;
-            }
-            const path = join(directory, entry.name);
-            let stats;
-            try {
-                stats = statSync(path);
-            }
-            catch {
-                continue;
-            }
-            if (!stats.isFile()) {
-                continue;
-            }
-            const mtimeMs = stats.mtimeMs;
-            const ageMs = Math.max(0, nowMs - mtimeMs);
-            snapshots.push({ path, mtimeMs, ageMs });
-        }
-    }
+        const manifest = readSnapshotManifest(group.manifest?.path);
+        const createdAtMs = manifestDateMs(manifest) ?? primary.stats.mtimeMs;
+        const databaseName = manifestDatabaseName(manifest) ?? inferDatabaseNameFromSnapshotName(group.stem, snapshotDatabaseNames);
+        const filestore = [...group.filestores].sort((left, right) => left.path.localeCompare(right.path))[0];
+        return [
+            {
+                name: typeof manifest?.name === 'string' && manifest.name.trim() ? manifest.name.trim() : group.stem,
+                path: primary.path,
+                dumpPath: primary.path,
+                manifestPath: group.manifest?.path,
+                databaseName,
+                createdAtMs,
+                createdAt: new Date(createdAtMs).toISOString(),
+                mtimeMs: primary.stats.mtimeMs,
+                ageMs: Math.max(0, nowMs - primary.stats.mtimeMs),
+                filestorePath: filestore?.path,
+                filestoreStatus: filestore ? 'found' : 'missing',
+            },
+        ];
+    });
     snapshots.sort((a, b) => b.mtimeMs - a.mtimeMs || a.path.localeCompare(b.path));
     const newestSnapshot = snapshots[0] ?? null;
     return {
@@ -98,11 +224,72 @@ export function findDatabaseSnapshots(targetDirectory, options = {}) {
         newestSnapshotAgeMs: newestSnapshot ? newestSnapshot.ageMs : null,
     };
 }
+export function restoreSnapshotPreflight(targetDirectory, snapshotName, requestedDatabase = 'devel', options = {}) {
+    const snapshots = findDatabaseSnapshots(targetDirectory, options);
+    const snapshot = snapshots.snapshots.find((candidate) => candidate.name === snapshotName || snapshotNameFromPath(candidate.path) === snapshotName);
+    const snapshotDirectory = join(targetDirectory, 'backups', 'snapshots');
+    const manifestPath = snapshot?.manifestPath ?? join(snapshotDirectory, `${snapshotName}.json`);
+    const manifest = readSnapshotManifest(fileExists(manifestPath) ? manifestPath : undefined);
+    const manifestDatabase = snapshot?.databaseName ?? manifestDatabaseName(manifest);
+    const dumpPath = snapshot?.dumpPath ?? join(snapshotDirectory, `${snapshotName}.dump`);
+    const filestorePath = snapshot?.filestorePath ??
+        (typeof manifest?.filestore === 'string' ? join(snapshotDirectory, manifest.filestore) : join(snapshotDirectory, `${snapshotName}.filestore.tar.gz`));
+    const dumpStatus = fileExists(dumpPath) ? 'found' : 'missing';
+    const filestoreStatus = fileExists(filestorePath) ? 'found' : 'missing';
+    const databaseMatches = manifestDatabase ? manifestDatabase === requestedDatabase : undefined;
+    const issues = [];
+    if (dumpStatus === 'missing') {
+        issues.push('missing snapshot dump');
+    }
+    if (filestoreStatus === 'missing') {
+        issues.push('missing snapshot filestore');
+    }
+    if (databaseMatches === false) {
+        issues.push(`snapshot database mismatch: manifest has ${manifestDatabase}, requested ${requestedDatabase}`);
+    }
+    return {
+        name: snapshotName,
+        requestedDatabase,
+        dumpPath,
+        dumpStatus,
+        filestorePath,
+        filestoreStatus,
+        manifestPath: fileExists(manifestPath) ? manifestPath : undefined,
+        manifestDatabase,
+        databaseMatches,
+        issues,
+    };
+}
 export function hasRecentDatabaseSnapshot(targetDirectory, options = {}) {
     const { maxAgeMs = defaultDatabaseSnapshotMaxAgeMs, ...scanOptions } = options;
     const result = findDatabaseSnapshots(targetDirectory, scanOptions);
     return result.newestSnapshotAgeMs !== null && result.newestSnapshotAgeMs <= maxAgeMs;
 }
+export function databaseSnapshotCatalogJson(targetDirectory) {
+    return {
+        schemaVersion: 1,
+        command: 'snapshot list',
+        ok: true,
+        snapshots: findDatabaseSnapshots(targetDirectory).snapshots,
+    };
+}
+export function renderDatabaseSnapshotCatalog(targetDirectory) {
+    const snapshots = findDatabaseSnapshots(targetDirectory).snapshots;
+    if (snapshots.length === 0) {
+        return 'No database snapshots found.\nNext: run ./moo snapshot [db] [snapshot-name].';
+    }
+    return [
+        'Database snapshots',
+        '',
+        ...snapshots.flatMap((snapshot) => [
+            `- ${snapshot.name}`,
+            `  Created: ${snapshot.createdAt}`,
+            `  Database: ${snapshot.databaseName ?? 'unknown'}`,
+            `  Dump: ${snapshot.dumpPath}`,
+            `  Filestore: ${snapshot.filestorePath ?? 'missing'} (${snapshot.filestoreStatus})`,
+        ]),
+    ].join('\n');
+}
 export function normalizeDatabaseListResult(result) {
     if (Array.isArray(result)) {
         return { ok: true, databases: result };

package/dist/doctor.js

@@ -1,12 +1,13 @@
-import { access, readFile, writeFile } from 'node:fs/promises';
+import { access, readdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { execa } from 'execa';
 import { detectComposeLayout, readEnvFile, selectedComposeEnvironment } from './compose-layout.js';
 import { dailyActionScripts } from './daily-actions.js';
 import { defaultPostgresVersion } from './external-templates.js';
 import { defaultOdooVersion, markerPath, 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 };
@@ -20,6 +21,35 @@ async function exists(path) {
         return false;
     }
 }
+async function legacyGeneratedEnvironmentErrors(target) {
+    const sourceRoot = join(target, 'odoo/custom/src');
+    const hasGeneratedSourceFiles = (await exists(join(sourceRoot, 'addons.yaml'))) ||
+        (await exists(join(sourceRoot, 'repos.yaml')));
+    if (!hasGeneratedSourceFiles) {
+        return [];
+    }
+    let legacySourceDirs;
+    try {
+        const entries = await readdir(sourceRoot, { withFileTypes: true });
+        legacySourceDirs = entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .filter((name) => !['private', 'oca', 'external'].includes(name))
+            .filter((name) => /^[A-Za-z0-9._-]+$/.test(name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    if (legacySourceDirs.length === 0) {
+        return [];
+    }
+    return [
+        `Legacy WPMoo environment is missing ${markerPath}; run ./moo reset --dry-run to preview generated metadata migration.`,
+        ...legacySourceDirs.map((path) => `Legacy source layout detected: odoo/custom/src/${path} will be registered as private/${path}.`),
+        'Run ./moo reset after reviewing the preview to write current metadata and generated files.',
+    ];
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -47,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;
@@ -57,16 +94,50 @@ 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;
+}
+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);
+    for (const probe of POSTGRES_DIAGNOSTICS_OPTIONAL_QUERIES) {
+        try {
+            Object.assign(diagnostics, await readPostgresDiagnosticQuery(target, runner, probe.query, timeoutMs));
+        }
+        catch {
+            // Optional probes use PostgreSQL functions that can require elevated roles.
+            // Their failure must not hide the core read-only health report.
+        }
+    }
+    return diagnostics;
+}
 function stripInlineComment(line) {
     const hashIndex = line.indexOf('#');
     if (hashIndex === -1)
@@ -221,6 +292,87 @@ function validatePort(name, env, errors) {
 function renderFailure(errors) {
     return ['WPMoo doctor failed:', ...errors.map((error) => `- ${error}`)].join('\n');
 }
+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') ||
+        line.includes('pg_stat_statements') ||
+        line.includes('long transaction') ||
+        line.includes('idle in transaction') ||
+        line.includes('table health') ||
+        line.includes('unused index') ||
+        line.includes('WAL') ||
+        line.includes('capacity risk')) {
+        return 'postgresql';
+    }
+    if (line.startsWith('OK compose files') ||
+        line.startsWith('OK .env ports') ||
+        line.startsWith('Missing compose file:') ||
+        line.startsWith('Missing compact compose overlay') ||
+        line.startsWith('Invalid Odoo version for compose file:') ||
+        line.includes('HTTP_PORT') ||
+        line.includes('GEVENT_PORT') ||
+        line.includes('PostgreSQL 18 compatibility issue')) {
+        return 'compose';
+    }
+    if (line.startsWith('OK source repos') ||
+        line.includes('source repo') ||
+        line.includes('sourceRepos') ||
+        line.includes('source manifest') ||
+        line.includes('source path') ||
+        line.includes('Git submodule') ||
+        line.includes('git submodules') ||
+        line.includes('GitHub CLI')) {
+        return 'source-repositories';
+    }
+    if (line.includes('Docker CLI') ||
+        line.includes('Docker Compose') ||
+        line.startsWith('OK docker')) {
+        return 'host-tools';
+    }
+    return 'generated-files';
+}
+function buildDoctorSections(checks, warnings, errors) {
+    const sections = new Map(doctorSectionDefinitions.map(({ id, title }) => [id, { id, title, checks: [], warnings: [], errors: [] }]));
+    for (const check of checks) {
+        sections.get(doctorSectionForLine(check))?.checks.push(check);
+    }
+    for (const warning of warnings) {
+        sections.get(doctorSectionForLine(warning))?.warnings.push(warning);
+    }
+    for (const error of errors) {
+        sections.get(doctorSectionForLine(error))?.errors.push(error);
+    }
+    return doctorSectionDefinitions
+        .map(({ id }) => sections.get(id))
+        .filter((section) => Boolean(section && (section.checks.length > 0 || section.warnings.length > 0 || section.errors.length > 0)));
+}
+function finalizeDoctorReport(report) {
+    report.sections = buildDoctorSections(report.checks, report.warnings, report.errors);
+    return report;
+}
+function renderSuccessfulDoctorReport(report) {
+    const lines = ['WPMoo doctor'];
+    const sections = report.sections ?? buildDoctorSections(report.checks, report.warnings, report.errors);
+    for (const section of sections) {
+        lines.push(section.title);
+        lines.push(...section.checks);
+        lines.push(...section.warnings.map((warning) => `WARN ${warning}`));
+    }
+    lines.push('Doctor checks passed.');
+    return lines.join('\n');
+}
 function isNotGitCheckoutError(error) {
     return commandErrorText(error).toLowerCase().includes('not a git repository');
 }
@@ -318,8 +470,15 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
         metadata = await readMetadata(target);
     }
     catch (error) {
-        errors.push(errorMessage(error));
-        return report;
+        const message = errorMessage(error);
+        if (message === `Missing metadata file: ${markerPath}`) {
+            const legacyErrors = await legacyGeneratedEnvironmentErrors(target);
+            errors.push(...(legacyErrors.length > 0 ? legacyErrors : [message]));
+        }
+        else {
+            errors.push(message);
+        }
+        return finalizeDoctorReport(report);
     }
     checks.push(`OK metadata ${markerPath}`);
     const engine = metadataString(metadata, 'engine') ?? 'compose';
@@ -392,15 +551,30 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
     }
     catch (error) {
         errors.push(errorMessage(error));
-        return report;
+        return finalizeDoctorReport(report);
     }
     for (const repo of sourceRepos) {
-        const relativePath = sourceRepoPath(normalizeSourceType(repo.sourceType), repo.path);
-        if (!(await exists(join(target, relativePath))) && repo.path) {
-            errors.push(`Missing source repo path: ${relativePath}`);
+        const sourceType = normalizeSourceType(repo.sourceType);
+        const relativePath = sourceRepoPath(sourceType, repo.path);
+        if ((await exists(join(target, relativePath))) || !repo.path) {
+            continue;
+        }
+        const legacyPrivatePath = sourceType === 'private' ? `odoo/custom/src/${repo.path}` : undefined;
+        if (legacyPrivatePath && (await exists(join(target, legacyPrivatePath)))) {
+            warnings.push(`Legacy private source path in use: ${legacyPrivatePath}; move it to ${relativePath} when ready.`);
+            continue;
         }
+        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 = [];
@@ -454,7 +628,7 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
     }
     if (actualOptions.postgres) {
         try {
-            const postgresDiagnostics = await readPostgresDiagnostics(target, actualRunner);
+            const postgresDiagnostics = await readPostgresDiagnostics(target, actualRunner, postgresDiagnosticsTimeoutMs(actualOptions));
             const missingKeys = missingPostgresDiagnosticKeys(postgresDiagnostics);
             const malformedKeys = malformedPostgresDiagnosticKeys(postgresDiagnostics);
             if (missingKeys.length === 0 && malformedKeys.length === 0) {
@@ -536,7 +710,7 @@ export async function getDoctorReport(target = process.cwd(), runnerOrOptions =
         warnings.push(`GitHub CLI auth: ${errorMessage(error)}`);
     }
     report.ok = errors.length === 0;
-    return report;
+    return finalizeDoctorReport(report);
 }
 export async function runDoctor(target = process.cwd(), runnerOrOptions = realCommandRunner, options = {}) {
     const report = await getDoctorReport(target, runnerOrOptions, options);
@@ -555,12 +729,6 @@ export async function runDoctor(target = process.cwd(), runnerOrOptions = realCo
         }
         throw new Error(renderFailure(report.errors));
     }
-    const renderedReport = [
-        'WPMoo doctor',
-        ...report.checks,
-        ...report.warnings.map((warning) => `WARN ${warning}`),
-        'Doctor checks passed.',
-    ];
     if (report.appliedFixes.length > 0) {
         const postFixReport = await runDoctor(target, actualRunner, { ...actualOptions, fix: false });
         return [
@@ -570,5 +738,5 @@ export async function runDoctor(target = process.cwd(), runnerOrOptions = realCo
             postFixReport,
         ].join('\n');
     }
-    return renderedReport.join('\n');
+    return renderSuccessfulDoctorReport(report);
 }

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/github.js

@@ -5,14 +5,23 @@ export const realGitHub = {
         return { stdout: result.stdout, stderr: result.stderr };
     },
 };
+const githubSlugPartPattern = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/u;
+function isSafeGitHubSlugPart(value) {
+    return Boolean(value &&
+        githubSlugPartPattern.test(value) &&
+        value !== '.' &&
+        value !== '..' &&
+        !value.startsWith('-') &&
+        !value.includes('..'));
+}
 export function parseGitHubRepoUrl(repoUrl) {
     const normalized = repoUrl.trim().replace(/[?#].*$/, '').replace(/\/+$/, '').replace(/\.git$/, '');
     const httpsMatch = normalized.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)$/);
-    if (httpsMatch) {
+    if (httpsMatch && isSafeGitHubSlugPart(httpsMatch[1]) && isSafeGitHubSlugPart(httpsMatch[2])) {
         return { owner: httpsMatch[1], name: httpsMatch[2] };
     }
     const sshMatch = normalized.match(/^git@github\.com:([^/]+)\/([^/]+)$/);
-    if (sshMatch) {
+    if (sshMatch && isSafeGitHubSlugPart(sshMatch[1]) && isSafeGitHubSlugPart(sshMatch[2])) {
         return { owner: sshMatch[1], name: sshMatch[2] };
     }
     return undefined;