@wpmoo/toolkit 0.9.28 → 0.9.30

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,4 +1,4 @@
-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';
@@ -20,6 +20,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);
 }
@@ -221,6 +250,83 @@ 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: 'postgresql', title: 'PostgreSQL' },
+    { id: 'host-tools', title: 'Host tools' },
+];
+function doctorSectionForLine(line) {
+    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 +424,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,13 +505,20 @@ 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`);
     const manifestPath = join(target, sourceManifestPath);
@@ -536,7 +656,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 +675,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 +684,5 @@ export async function runDoctor(target = process.cwd(), runnerOrOptions = realCo
             postFixReport,
         ].join('\n');
     }
-    return renderedReport.join('\n');
+    return renderSuccessfulDoctorReport(report);
 }

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;

package/dist/help.js

@@ -32,7 +32,7 @@ Usage:
   npx @wpmoo/toolkit update <module[,module]> [db]
   npx @wpmoo/toolkit test <module[,module]> [--db <db>] [--mode auto|init|update] [--tags <tags>]
   npx @wpmoo/toolkit resetdb [db] [module[,module]]
-  npx @wpmoo/toolkit snapshot [db] [snapshot-name]
+  npx @wpmoo/toolkit snapshot [--list] [db] [snapshot-name]
   npx @wpmoo/toolkit restore-snapshot [--dry-run] <snapshot-name> [db]
   npx @wpmoo/toolkit lint
   npx @wpmoo/toolkit pot <module[,module]> [db] [output]
@@ -76,8 +76,9 @@ 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 deprecated compatibility aliases.
+  npx wpmoo is an optional best-effort short alias; use @wpmoo/toolkit for automation.
+  npx @wpmoo/odoo and npx @wpmoo/odoo-dev remain deprecated compatibility aliases through 1.x.
+  Removing a compatibility alias requires a future major release and prior notice.
 
 Daily actions:
   Daily actions must be run from a generated environment root containing .wpmoo/odoo.json.
@@ -90,11 +91,13 @@ Lifecycle 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.
+  Time-bounded local approvals may also be recorded in .wpmoo/approvals.jsonl.
 
 Cockpit:
   Run npx @wpmoo/toolkit inside a generated environment to open the cockpit.
-  Use Command palette / to search slash commands across services, modules, database,
-  diagnostics, repositories, and maintenance categories.
+  Use Command palette / to search slash commands such as /test, /modules,
+  /install-module, /doctor, and /safe-reset.
+  Large module lists switch to searchable selection by module, repo, or source type.
   Direct commands such as npx @wpmoo/toolkit status and npx @wpmoo/toolkit test remain available.
 
 Wizard local-only path:
@@ -139,7 +142,7 @@ Task recipes:
   Run tests:
     npx @wpmoo/toolkit test <module[,module]> [--db <db>] [--mode auto|init|update] [--tags <tags>]
   Safe reset and recover:
-    npx @wpmoo/toolkit snapshot [db] [snapshot-name]
+    npx @wpmoo/toolkit snapshot [--list] [db] [snapshot-name]
     npx @wpmoo/toolkit reset --dry-run
     npx @wpmoo/toolkit reset
     npx @wpmoo/toolkit restore-snapshot --dry-run <snapshot-name> [db]
@@ -160,6 +163,11 @@ Machine-readable JSON output:
     doctor --json --postgres includes a structured postgres object for automation.
     Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
+JSON compatibility policy:
+  Automation should ignore unknown fields.
+  Minor and patch releases may add optional fields.
+  Removing, renaming, or changing the meaning of a documented field requires a major release or schemaVersion bump.
+
 Example:
   npx @wpmoo/toolkit create \\
     --product odoo_sample_module \\

package/dist/module-actions.js

@@ -41,6 +41,26 @@ function validateSupportedOdooVersion(value) {
 function sourceRepoPath(target, sourceType, repoPath) {
     return pathUnderBase(join(target, `odoo/custom/src/${sourceType}`), repoPath, 'repo path');
 }
+async function readableSourceRepoPath(target, sourceType, repoPath) {
+    const primary = sourceRepoPath(target, sourceType, repoPath);
+    try {
+        await readdir(primary);
+        return primary;
+    }
+    catch {
+        if (sourceType !== 'private') {
+            return primary;
+        }
+    }
+    const legacy = pathUnderBase(join(target, 'odoo/custom/src'), repoPath, 'repo path');
+    try {
+        await readdir(legacy);
+        return legacy;
+    }
+    catch {
+        return primary;
+    }
+}
 function modulePath(target, sourceType, repoPath, moduleName) {
     return pathUnderBase(sourceRepoPath(target, sourceType, repoPath), moduleName, 'module name');
 }
@@ -410,12 +430,13 @@ export async function listModulesInSourceRepo(target, repoPath, sourceType) {
     const safeRepoPath = validateRepoPath(repoPath);
     const resolvedSourceType = normalizeSourceType(sourceType);
     try {
-        const entries = await readdir(sourceRepoPath(target, resolvedSourceType, safeRepoPath), { withFileTypes: true });
+        const repoRoot = await readableSourceRepoPath(target, resolvedSourceType, safeRepoPath);
+        const entries = await readdir(repoRoot, { withFileTypes: true });
         const modules = await Promise.all(entries
             .filter((entry) => entry.isDirectory())
             .map(async (entry) => {
             try {
-                await readFile(join(sourceRepoPath(target, resolvedSourceType, safeRepoPath), entry.name, '__manifest__.py'), 'utf8');
+                await readFile(join(repoRoot, entry.name, '__manifest__.py'), 'utf8');
                 return entry.name;
             }
             catch {

package/dist/module-manifest.js

@@ -262,12 +262,18 @@ function validateManifest(manifest) {
     if (manifest.data !== undefined && !Array.isArray(manifest.data)) {
         throw new Error('invalid manifest: data must be a list of strings');
     }
+    if (manifest.demo !== undefined && !Array.isArray(manifest.demo)) {
+        throw new Error('invalid manifest: demo must be a list of strings');
+    }
     if (Array.isArray(manifest.depends) && !manifest.depends.every((entry) => typeof entry === 'string')) {
         throw new Error('invalid manifest: depends must be a list of strings');
     }
     if (Array.isArray(manifest.data) && !manifest.data.every((entry) => typeof entry === 'string')) {
         throw new Error('invalid manifest: data must be a list of strings');
     }
+    if (Array.isArray(manifest.demo) && !manifest.demo.every((entry) => typeof entry === 'string')) {
+        throw new Error('invalid manifest: demo must be a list of strings');
+    }
     return manifest;
 }
 export function parseOdooManifest(content) {