@wpmoo/odoo 0.8.57 → 0.8.59

package/README.md

@@ -16,7 +16,7 @@ It gives Odoo teams a repeatable environment layout, a guided cockpit for daily
 ## Why WPMoo Odoo
 
 - Create a local Odoo development environment from a dev repository and one or more source repositories.
-- Keep product source repositories under `odoo/custom/src/private` as Git submodules pinned to the selected Odoo branch.
+- Keep product source repositories under `odoo/custom/src/private`, `odoo/custom/src/oca`, or `odoo/custom/src/external` as Git submodules pinned to the selected Odoo branch.
 - Copy Docker Compose resources from the standalone `wpmoo-org/odoo-docker-compose` resource instead of embedding large runtime assets in the TypeScript package.
 - Optionally copy project-local Agent Skills from `wpmoo-org/odoo-skills` into generated environments.
 - Use either a guided terminal cockpit or direct CLI commands for the same lifecycle tasks.
@@ -194,8 +194,9 @@ odoo_sample_module_dev/
 |-- odoo/
 |   `-- custom/
 |       `-- src/
-|           `-- private/
-|               `-- odoo_sample_module/
+|           |-- private/
+|           |-- oca/
+|           `-- external/
 `-- scripts/
 ```
 
@@ -242,6 +243,18 @@ npx @wpmoo/odoo add-repo \
   --init-empty-repos
 ```
 
+Pin source repositories to dedicated source directories:
+
+```bash
+npx @wpmoo/odoo add-repo \
+  --repo-url https://github.com/OCA/sale-workflow.git \
+  --source-type oca
+
+npx @wpmoo/odoo add-repo \
+  --repo-url https://github.com/example-org/odoo_external_tool.git \
+  --source-type external
+```
+
 GitHub CLI is optional for repository setup. When it is available and authenticated, the interactive flow can:
 
 - detect the owner or organization from the current environment;
@@ -299,7 +312,10 @@ It reports whether the environment is detected, which Odoo version is selected,
 npx @wpmoo/odoo doctor
 ```
 
-It validates metadata, engine support, selected compose files, daily scripts, source repo paths, `.env` ports, Docker CLI access, Docker Compose access, Git submodule state, and GitHub CLI authentication when available.
+It validates metadata, engine support, selected compose files, source repo paths,
+daily scripts, `.env` settings, Docker CLI access, Docker Compose access, GitHub CLI
+authentication when available, and PostgreSQL 18 compatibility in compose mount
+targets (for mounts to `/var/lib/postgresql/data` or `/var/lib/postgresql/18/docker`).
 
 Safe reset refreshes generated environment files without deleting product source code:
 
@@ -309,9 +325,19 @@ npx @wpmoo/odoo reset
 
 Safe reset updates generated files such as `.wpmoo/odoo.json`, `moo`,
 `.gitignore`, `.env.example`, generated docs, compose assets, and optional
-Agent Skills. It does not touch source repo folders under
+Agent Skills. Compose overlays like `compose.yaml` and `compose/dev.yaml` are
+also refreshed from the current compose template source.
+
+It does not touch source repo folders under
 `odoo/custom/src/private`, module source code, Git history, remotes, or
-branches. Legacy compose template paths from older scaffolds can remain
+branches. It also preserves local runtime artifacts and custom source layout
+content:
+
+- `.env`, `data`, and `backups`
+- `odoo/custom/src/oca`, `odoo/custom/src/external`, `odoo/custom/patches`,
+  `odoo/custom/manifests`, and their existing contents
+
+Legacy compose template paths from older scaffolds can remain
 (`docs/assets/`, `test/`, `.github/`) until you remove them manually.
 
 Recommended recovery pattern:

package/dist/cli.js

@@ -79,6 +79,19 @@ function stringOption(values, key) {
     const value = values[key];
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
+function optionalSourceTypeValue(values) {
+    const value = stringOption(values, 'sourceType');
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === 'private' || value === 'oca' || value === 'external') {
+        return value;
+    }
+    throw new Error(`Invalid value for --source-type: ${value}`);
+}
+function sourceTypeValue(values) {
+    return optionalSourceTypeValue(values) ?? 'private';
+}
 function booleanOption(values, key, fallback) {
     const value = values[key];
     if (value === undefined)
@@ -102,6 +115,12 @@ function shellQuote(value) {
         return value;
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
+function renderedSourceRepoPath(target, sourceType, repoPath) {
+    if (repoPath) {
+        return `${target}/odoo/custom/src/${sourceType}/${repoPath}`;
+    }
+    return `${target}/odoo/custom/src/${sourceType}`;
+}
 function renderPostCreateGuidance(target, cwd) {
     const relativeTarget = relative(cwd, target) || '.';
     return yellow([
@@ -309,6 +328,7 @@ async function addRepoOptionsFromArgs(argv) {
         target,
         repoUrl: normalizeRepositoryUrl(repoUrl),
         repoPath: stringOption(values, 'repo') ?? stringOption(values, 'sourcePath'),
+        sourceType: sourceTypeValue(values),
         odooVersion: await commandOdooVersion(target, stringOption(values, 'odooVersion')),
         initEmptyRepos: booleanOption(values, 'initEmptyRepos', false),
         stage: booleanOption(values, 'stage', true),
@@ -335,6 +355,7 @@ async function addRepoOptionsFromPrompts(showIntro = true, cancelAction = 'exit'
     return {
         target,
         repoUrl,
+        sourceType: 'private',
         odooVersion,
         initEmptyRepos: true,
         stage: true,
@@ -438,6 +459,7 @@ function removeRepoOptionsFromArgs(argv) {
     return {
         target: resolve(stringOption(values, 'target') ?? process.cwd()),
         repoPath,
+        sourceType: optionalSourceTypeValue(values),
         stage: booleanOption(values, 'stage', true),
     };
 }
@@ -633,7 +655,7 @@ async function runCockpitCommand(command, cwd) {
         const options = await addRepoOptionsFromPrompts(false, 'back');
         await ensureAddRepoGitHubRepository(options, 'back');
         await addModuleRepo(options);
-        note(`Added source repo under ${options.target}/odoo/custom/src/private.`, 'Done');
+        note(`Added source repo under ${renderedSourceRepoPath(options.target, options.sourceType ?? 'private')}.`, 'Done');
         return 'continue';
     }
     if (command.id === 'remove-repo') {
@@ -724,7 +746,7 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
         if (options) {
             console.log(renderBanner());
             await addModuleRepo(options);
-            outro(`Added source repo under ${options.target}/odoo/custom/src/private.`);
+            outro(`Added source repo under ${renderedSourceRepoPath(options.target, options.sourceType ?? 'private', options.repoPath)}.`);
             return;
         }
         await showStartup(argv, skipUpdateCheck);

package/dist/doctor.js

@@ -3,6 +3,7 @@ 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 } from './environment.js';
 const realCommandRunner = async (command, args, options) => {
     const result = await execa(command, args, { cwd: options.cwd });
@@ -35,6 +36,58 @@ function commandErrorText(error) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+const incompatiblePostgres18MountTargets = ['/var/lib/postgresql/data', '/var/lib/postgresql/18/docker'];
+function parsePostgresMajorFromValue(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d{1,3}$/.test(trimmed)) {
+        return trimmed;
+    }
+    const match = trimmed.match(/postgres:([0-9]{1,3})(?:[-._][A-Za-z0-9._-]+)?(?:@[\w:.-]+)?/i);
+    return match?.[1];
+}
+function stripInlineComment(line) {
+    const hashIndex = line.indexOf('#');
+    if (hashIndex === -1)
+        return line;
+    return line.slice(0, hashIndex);
+}
+function hasInvalidPostgres18Mount(line, mountTarget) {
+    const escaped = mountTarget.replaceAll('.', '\\.').replaceAll('/', '\\/');
+    const shortPatterns = [
+        new RegExp(`^\\s*-\\s+.+:\\s*['"]?${escaped}['"]?(?:\\s|:|$)`),
+        new RegExp(`^\\s*-\\s*['"]?${escaped}['"]?(?:\\s|$)`),
+        new RegExp(`^\\s*target:\\s*['"]?${escaped}['"]?(?:\\s|$)`),
+    ];
+    return shortPatterns.some((pattern) => pattern.test(line));
+}
+function invalidPostgres18MountTargetsInCompose(content) {
+    const badTargets = new Set();
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = stripInlineComment(rawLine).trim();
+        if (!line)
+            continue;
+        for (const target of incompatiblePostgres18MountTargets) {
+            if (hasInvalidPostgres18Mount(line, target)) {
+                badTargets.add(target);
+            }
+        }
+    }
+    return [...badTargets];
+}
+function inferPostgresVersion(metadata, odooVersion, env) {
+    const envPostgresImage = env?.get('POSTGRES_IMAGE')?.trim();
+    const envPostgresMajor = parsePostgresMajorFromValue(envPostgresImage);
+    if (envPostgresMajor) {
+        return envPostgresMajor;
+    }
+    const explicitPostgres = parsePostgresMajorFromValue(metadataString(metadata, 'postgresVersion'));
+    if (explicitPostgres) {
+        return explicitPostgres;
+    }
+    return defaultPostgresVersion(odooVersion);
+}
 function sourceReposFromMetadata(metadata) {
     const sourceRepos = metadata.sourceRepos;
     if (!Array.isArray(sourceRepos))
@@ -142,6 +195,24 @@ export async function runDoctor(target = process.cwd(), runner = realCommandRunn
     }
     else {
         lines.push(`OK compose files ${composeLayout.files.join(', ')}`);
+        const postgresVersion = inferPostgresVersion(metadata, odooVersion, env);
+        if (postgresVersion === '18') {
+            for (const file of composeLayout.files) {
+                const composePath = join(target, file);
+                let content;
+                try {
+                    content = await readFile(composePath, 'utf8');
+                }
+                catch (error) {
+                    errors.push(`Cannot read compose file for compatibility check: ${file}: ${errorMessage(error)}`);
+                    continue;
+                }
+                const badMounts = invalidPostgres18MountTargetsInCompose(content);
+                for (const badMount of badMounts) {
+                    errors.push(`PostgreSQL 18 compatibility issue in '${file}': mount target '${badMount}' is invalid; recommend using '/var/lib/postgresql'`);
+                }
+            }
+        }
     }
     const scriptNames = Object.values(dailyActionScripts);
     const scriptErrorCount = errors.length;

package/dist/environment.js

@@ -1,6 +1,7 @@
-import { access, readFile } from 'node:fs/promises';
+import { access, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { packageName, packageVersion } from './version.js';
+const validSourceTypes = ['private', 'oca', 'external'];
 export const markerPath = '.wpmoo/odoo.json';
 export const defaultOdooVersion = '19.0';
 async function exists(path) {
@@ -34,23 +35,90 @@ export function environmentMetadata(options) {
 export function renderEnvironmentMetadata(options) {
     return `${JSON.stringify(environmentMetadata(options), null, 2)}\n`;
 }
+function normalizeSourceType(sourceType) {
+    const normalized = sourceType ?? 'private';
+    return validSourceTypes.includes(normalized) ? normalized : 'private';
+}
+function normalizeMetadataSourceRepo(repo) {
+    if (!repo || typeof repo !== 'object') {
+        return undefined;
+    }
+    const candidate = repo;
+    const path = typeof candidate.path === 'string' ? candidate.path : '';
+    const url = typeof candidate.url === 'string' ? candidate.url : '';
+    const addons = Array.isArray(candidate.addons) ? candidate.addons.filter((item) => typeof item === 'string') : [];
+    const sourceType = normalizeSourceType(typeof candidate.sourceType === 'string' ? candidate.sourceType : undefined);
+    if (!path || !url) {
+        return undefined;
+    }
+    return { ...candidate, path, url, addons, sourceType };
+}
+function sourceRepoWithType(repo) {
+    return {
+        ...repo,
+        sourceType: normalizeSourceType(repo.sourceType),
+    };
+}
+function withoutPathDuplicates(repos) {
+    const byPath = new Map();
+    repos.forEach((repo) => {
+        const normalized = sourceRepoWithType(repo);
+        byPath.set(`${normalized.sourceType}:${normalized.path}`, normalized);
+    });
+    return Array.from(byPath.values());
+}
 export async function readEnvironmentMetadata(target) {
     try {
         const content = await readFile(join(target, markerPath), 'utf8');
-        return JSON.parse(content);
+        const metadata = JSON.parse(content);
+        if (!metadata?.sourceRepos || !Array.isArray(metadata.sourceRepos)) {
+            return metadata;
+        }
+        metadata.sourceRepos = metadata.sourceRepos
+            .map(normalizeMetadataSourceRepo)
+            .filter((repo) => Boolean(repo));
+        metadata.sourceRepos = withoutPathDuplicates(metadata.sourceRepos);
+        return metadata;
     }
     catch {
         return undefined;
     }
 }
+async function writeEnvironmentMetadata(target, metadata) {
+    const content = `${JSON.stringify({
+        ...metadata,
+        sourceRepos: metadata.sourceRepos.map(sourceRepoWithType),
+    }, null, 2)}\n`;
+    await writeFile(join(target, markerPath), content, 'utf8');
+}
+export async function upsertSourceRepoMetadata(target, sourceRepo) {
+    const metadata = await readEnvironmentMetadata(target);
+    if (!metadata)
+        return;
+    const normalizedRepo = sourceRepoWithType(sourceRepo);
+    const sources = metadata.sourceRepos.filter((repo) => !(repo.path === normalizedRepo.path && normalizeSourceType(repo.sourceType) === normalizedRepo.sourceType));
+    sources.push(normalizedRepo);
+    metadata.sourceRepos = withoutPathDuplicates(sources);
+    await writeEnvironmentMetadata(target, metadata);
+}
+export async function removeSourceRepoMetadata(target, repoPath, sourceType) {
+    const metadata = await readEnvironmentMetadata(target);
+    if (!metadata)
+        return;
+    const normalizedType = normalizeSourceType(sourceType);
+    metadata.sourceRepos = metadata.sourceRepos.filter((repo) => !(repo.path === repoPath && normalizeSourceType(repo.sourceType) === normalizedType));
+    await writeEnvironmentMetadata(target, metadata);
+}
 export async function detectDevelopmentEnvironment(target) {
     if (await readEnvironmentMetadata(target)) {
         return { isEnvironment: true, source: 'marker' };
     }
     const hasAddonsYaml = await exists(join(target, 'odoo/custom/src/addons.yaml'));
     const hasReposYaml = await exists(join(target, 'odoo/custom/src/repos.yaml'));
-    const hasPrivateDir = await exists(join(target, 'odoo/custom/src/private'));
-    if (hasAddonsYaml && hasReposYaml && hasPrivateDir) {
+    const hasSourceDir = (await exists(join(target, 'odoo/custom/src/private'))) ||
+        (await exists(join(target, 'odoo/custom/src/oca'))) ||
+        (await exists(join(target, 'odoo/custom/src/external')));
+    if (hasAddonsYaml && hasReposYaml && hasSourceDir) {
         return { isEnvironment: true, source: 'layout' };
     }
     return { isEnvironment: false, source: 'none' };

package/dist/help.js

@@ -7,7 +7,7 @@ Usage:
   npx @wpmoo/odoo
   npx @wpmoo/odoo create --product <slug> [--target <path>] --dev-repo-url <url> --source-repo-url <url>
   npx @wpmoo/odoo status
-  npx @wpmoo/odoo add-repo --repo-url <url>
+  npx @wpmoo/odoo add-repo --repo-url <url> [--source-type private|oca|external]
   npx @wpmoo/odoo remove-repo --repo <name>
   npx @wpmoo/odoo add-module --repo <source-repo> --module <module-name>
   npx @wpmoo/odoo remove-module --repo <source-repo> --module <module-name>
@@ -45,6 +45,7 @@ Options:
   --http-port <port>           Host HTTP port written to .env.example.
   --gevent-port <port>         Host gevent/live chat port written to .env.example.
   --repo-url <url>             Source repo URL for add-repo.
+  --source-type <category>     Source repo category for add-repo/remove-repo. 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.
   --delete-files               Also delete module files in remove-module. Default: false.
@@ -90,7 +91,7 @@ Task recipes:
   Create local-only environment:
     npx @wpmoo/odoo
   Add source repo:
-    npx @wpmoo/odoo add-repo --repo-url <url>
+    npx @wpmoo/odoo add-repo --repo-url <url> --source-type oca
   Add module:
     npx @wpmoo/odoo add-module --repo <source-repo> --module <module-name>
   Run tests:

package/dist/repo-actions.js

@@ -1,17 +1,53 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { addSourceRepoToAddonsYaml, removeSourceRepoFromAddonsYaml } from './addons-yaml.js';
-import { readEnvironmentMetadata } from './environment.js';
+import { readEnvironmentMetadata, removeSourceRepoMetadata, upsertSourceRepoMetadata } from './environment.js';
 import { ensureRemoteHasBranch, ensureSubmodule, hasUncommittedChanges, realGit, removeSubmodule, stageAll, } from './git.js';
 import { isValidPathSegment, validateRepoPath } from './path-validation.js';
 import { inferRepoPath } from './repo-url.js';
 export const addonsYamlHeader = `# Addons activated from source submodules.
 #
-# Source repos are managed as Git submodules under odoo/custom/src/private.
+# Source repos are managed as Git submodules under odoo/custom/src/private (product code).
+# OCA/external source repos can be placed under odoo/custom/src/oca and odoo/custom/src/external.
 # Do not duplicate these same repos in repos.yaml.
 `;
-function privateSubmodulePath(repoPath) {
-    return `odoo/custom/src/private/${validateRepoPath(repoPath)}`;
+const validSourceTypes = ['private', 'oca', 'external'];
+function normalizeSourceType(value) {
+    return validSourceTypes.includes(value) ? value : 'private';
+}
+function sourceSubmodulePath(sourceType, repoPath) {
+    return `odoo/custom/src/${sourceType}/${validateRepoPath(repoPath)}`;
+}
+function resolveSourceTypeFromSubmodulePath(submodulePath) {
+    const match = /^odoo\/custom\/src\/(private|oca|external)\//.exec(submodulePath);
+    if (!match)
+        return undefined;
+    return match[1];
+}
+async function listGitmoduleRepos(target) {
+    try {
+        const gitmodules = await readFile(join(target, '.gitmodules'), 'utf8');
+        return [...gitmodules.matchAll(/^\s*path\s*=\s*odoo\/custom\/src\/(private|oca|external)\/(.+)$/gm)]
+            .map((match) => ({ sourceType: match[1], path: match[2].trim() }))
+            .filter((entry) => isValidPathSegment(entry.path));
+    }
+    catch {
+        return [];
+    }
+}
+async function resolveSubmodulePathFromConfig(target, repoPath, sourceType) {
+    if (sourceType) {
+        return sourceSubmodulePath(sourceType, validateRepoPath(repoPath));
+    }
+    const repoMatches = (await listGitmoduleRepos(target)).filter((repo) => repo.path === repoPath);
+    if (repoMatches.length === 1) {
+        return sourceSubmodulePath(repoMatches[0].sourceType, repoPath);
+    }
+    if (repoMatches.length > 1) {
+        const sorted = repoMatches.map((repo) => repo.sourceType).sort();
+        throw new Error(`Source repo ${repoPath} exists in multiple source directories: ${sorted.join(', ')}. Provide --source-type to disambiguate.`);
+    }
+    return sourceSubmodulePath('private', repoPath);
 }
 export async function readAddonsYaml(target) {
     try {
@@ -55,20 +91,29 @@ export async function syncComposeOdooConfAddonsPath(target) {
 }
 export async function addModuleRepo(options, git = realGit) {
     const repoPath = validateRepoPath(options.repoPath?.trim() || inferRepoPath(options.repoUrl));
-    const submodulePath = privateSubmodulePath(repoPath);
+    const sourceType = normalizeSourceType(options.sourceType);
+    const submodulePath = sourceSubmodulePath(sourceType, repoPath);
     await ensureRemoteHasBranch(git, options.target, options.repoUrl, options.odooVersion, options.initEmptyRepos);
-    await mkdir(join(options.target, 'odoo/custom/src/private'), { recursive: true });
+    await mkdir(join(options.target, 'odoo/custom/src', sourceType), { recursive: true });
     await ensureSubmodule(git, options.target, options.repoUrl, options.odooVersion, submodulePath);
     const listedRepos = await listModuleRepos(options.target);
     if (!listedRepos.includes(repoPath)) {
         throw new Error(`Source repo was added but is not registered in .gitmodules: ${repoPath}`);
     }
+    await upsertSourceRepoMetadata(options.target, {
+        url: options.repoUrl,
+        path: repoPath,
+        addons: [repoPath],
+        sourceType,
+    });
     if (!(await isComposeEnvironment(options.target))) {
         const addonsYaml = await readAddonsYaml(options.target);
-        await writeAddonsYaml(options.target, addSourceRepoToAddonsYaml(addonsYaml, {
-            path: repoPath,
-            addons: [repoPath],
-        }));
+        if (sourceType === 'private') {
+            await writeAddonsYaml(options.target, addSourceRepoToAddonsYaml(addonsYaml, {
+                path: repoPath,
+                addons: [repoPath],
+            }));
+        }
     }
     await syncComposeOdooConfAddonsPath(options.target);
     if (options.stage) {
@@ -76,28 +121,24 @@ export async function addModuleRepo(options, git = realGit) {
     }
 }
 export async function listModuleRepos(target) {
-    try {
-        const gitmodules = await readFile(join(target, '.gitmodules'), 'utf8');
-        return [...gitmodules.matchAll(/^\s*path\s*=\s*odoo\/custom\/src\/private\/(.+)$/gm)]
-            .map((match) => match[1].trim())
-            .filter((repoPath) => repoPath && isValidPathSegment(repoPath))
-            .sort();
-    }
-    catch {
-        return [];
-    }
+    return (await listGitmoduleRepos(target)).map((repo) => repo.path).sort();
 }
 export async function removeModuleRepo(options, git = realGit) {
     const repoPath = validateRepoPath(options.repoPath);
-    const submodulePath = privateSubmodulePath(repoPath);
+    const sourceType = options.sourceType ? normalizeSourceType(options.sourceType) : undefined;
+    const submodulePath = await resolveSubmodulePathFromConfig(options.target, repoPath, sourceType);
     const fullSubmodulePath = join(options.target, submodulePath);
+    const resolvedSourceType = sourceType ?? resolveSourceTypeFromSubmodulePath(submodulePath);
     if (await hasUncommittedChanges(git, fullSubmodulePath)) {
         throw new Error(`Cannot remove ${repoPath}: submodule has uncommitted changes.`);
     }
     await removeSubmodule(git, options.target, submodulePath);
+    await removeSourceRepoMetadata(options.target, repoPath, resolvedSourceType);
     if (!(await isComposeEnvironment(options.target))) {
         const addonsYaml = await readAddonsYaml(options.target);
-        await writeAddonsYaml(options.target, removeSourceRepoFromAddonsYaml(addonsYaml, repoPath));
+        if (resolvedSourceType === 'private') {
+            await writeAddonsYaml(options.target, removeSourceRepoFromAddonsYaml(addonsYaml, repoPath));
+        }
     }
     await syncComposeOdooConfAddonsPath(options.target);
     if (options.stage) {

package/dist/safe-reset.js

@@ -1,12 +1,45 @@
-import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { readEnvironmentMetadata } from './environment.js';
+import { environmentMetadata, readEnvironmentMetadata } from './environment.js';
 import { applyExternalAsset, writeTextFile } from './external-assets.js';
 import { plannedExternalAssetOptions, renderComposeEnvExample } from './external-templates.js';
 import { realGit, stageAll } from './git.js';
 import { isValidPathSegment, validateAddonName, validateRepoPath } from './path-validation.js';
 import { listModuleRepos, readAddonsYaml } from './repo-actions.js';
 import { generatedFiles } from './scaffold.js';
+const safeResetProtectedPaths = [
+    'data',
+    'backups',
+    '.env',
+    '.gitmodules',
+    'odoo/custom/src/private',
+    'odoo/custom/src/oca',
+    'odoo/custom/src/external',
+    'odoo/custom/patches',
+    'odoo/custom/manifests',
+].map((path) => path.replace(/\/$/, ''));
+const safeResetProtectedGeneratedReadmes = new Set([
+    'odoo/custom/src/private/README.md',
+    'odoo/custom/src/oca/README.md',
+    'odoo/custom/src/external/README.md',
+    'odoo/custom/patches/README.md',
+    'odoo/custom/manifests/README.md',
+]);
+function isProtectedGeneratedFile(filePath) {
+    return safeResetProtectedGeneratedReadmes.has(filePath);
+}
+function mergeEnvironmentMetadata(target, options) {
+    const generated = environmentMetadata(options);
+    return readFile(join(target, '.wpmoo/odoo.json'), 'utf8')
+        .then((content) => JSON.parse(content))
+        .then((existing) => {
+        if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+            return `${JSON.stringify(generated, null, 2)}\n`;
+        }
+        return `${JSON.stringify({ ...existing, ...generated, sourceRepos: generated.sourceRepos }, null, 2)}\n`;
+    })
+        .catch(() => `${JSON.stringify(generated, null, 2)}\n`);
+}
 export function renderSafeResetPreview(target, stage) {
     return [
         'Safe reset will refresh generated WPMoo environment files.',
@@ -29,8 +62,12 @@ export function renderSafeResetPreview(target, stage) {
         '- source repo folders under odoo/custom/src/private',
         '- module source code',
         '- Git history, remotes, or branches',
+        '- .env, data, and backups',
+        '- custom source layout directories (oca, external, patches, manifests)',
         '- Legacy compose template files may remain until manually removed: docs/assets/, test/, .github/',
         '',
+        'Preview-only output; files are not changed until reset is executed.',
+        '',
         stage ? 'Generated changes will be staged with git add .' : 'Generated changes will not be staged.',
     ].join('\n');
 }
@@ -42,9 +79,7 @@ function safeResetExternalAssetOptions(options) {
         ...assetOptions,
         exclude: [
             ...(assetOptions.exclude ?? []),
-            '.env',
-            '.gitmodules',
-            'odoo/custom/src/private',
+            ...safeResetProtectedPaths,
         ],
     }));
 }
@@ -88,6 +123,15 @@ async function readSubmoduleUrl(target, repoPath) {
         return `odoo/custom/src/private/${safeRepoPath}`;
     }
 }
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function inferOptions(target) {
     const metadata = await readEnvironmentMetadata(target);
     const addonsYaml = await readAddonsYaml(target);
@@ -130,6 +174,12 @@ export async function safeResetEnvironment(options, git = realGit) {
     const files = generatedFiles(scaffoldOptions);
     const externalAssets = safeResetExternalAssetOptions(scaffoldOptions);
     for (const file of files) {
+        if (file.path === '.wpmoo/odoo.json') {
+            continue;
+        }
+        if (isProtectedGeneratedFile(file.path) && (await pathExists(join(options.target, file.path)))) {
+            continue;
+        }
         if (file.path === 'odoo/custom/src/addons.yaml') {
             continue;
         }
@@ -143,6 +193,7 @@ export async function safeResetEnvironment(options, git = realGit) {
     for (const assetOptions of externalAssets) {
         await applyExternalAsset(assetOptions, git);
     }
+    await writeTextFile(join(options.target, '.wpmoo/odoo.json'), await mergeEnvironmentMetadata(options.target, scaffoldOptions));
     await writeTextFile(join(options.target, '.env.example'), renderComposeEnvExample(scaffoldOptions));
     if (options.stage) {
         await stageAll(git, options.target);

package/dist/scaffold.js

@@ -22,6 +22,33 @@ function validateScaffoldOptions(options) {
 }
 export function generatedFiles(options) {
     const safeOptions = validateScaffoldOptions(options);
+    const sourceDirReadmes = [
+        {
+            path: 'odoo/custom/src/private/README.md',
+            title: 'private',
+            body: 'Project-owned/private addon repositories go here.',
+        },
+        {
+            path: 'odoo/custom/src/oca/README.md',
+            title: 'oca',
+            body: 'OCA repositories go here, for example server-tools, web, queue.',
+        },
+        {
+            path: 'odoo/custom/src/external/README.md',
+            title: 'external',
+            body: 'Non-OCA third-party, vendor, and community addon repositories go here.',
+        },
+        {
+            path: 'odoo/custom/patches/README.md',
+            title: 'patches',
+            body: 'Local patches for upstream/vendor/OCA repositories go here.',
+        },
+        {
+            path: 'odoo/custom/manifests/README.md',
+            title: 'manifests',
+            body: 'Manifest/lock/list files for external sources and pinned revisions go here.',
+        },
+    ];
     const files = [
         { path: markerPath, content: renderEnvironmentMetadata(safeOptions) },
         { path: 'moo', content: renderMooDelegationScript(), mode: 0o755 },
@@ -32,10 +59,10 @@ export function generatedFiles(options) {
     ];
     return [
         ...files,
-        {
-            path: 'odoo/custom/src/private/README.md',
-            content: renderPlaceholder('private', 'WPMoo source repositories are added here as Git submodules.'),
-        },
+        ...sourceDirReadmes.map((readme) => ({
+            path: readme.path,
+            content: renderPlaceholder(readme.title, readme.body),
+        })),
     ];
 }
 async function writeGeneratedFiles(target, files) {

package/dist/templates.js

@@ -22,46 +22,62 @@ function hasSourceRepos(options) {
 }
 function repositoryLayout(options) {
     const sourceRepoRows = hasSourceRepos(options)
-        ? options.sourceRepos.map((repo) => `│               ├── ${repo.path}/`).join('\n')
-        : '│               └── (add repos with ./moo add-repo)';
-    return `${options.devRepo}/
-├── compose.yaml
-├── compose/
-│   ├── dev.yaml
-│   ├── debug.yaml
-│   ├── test.yaml
-│   ├── stage.yaml
-│   ├── prod.yaml
-│   ├── proxy.yaml
-│   └── tools.yaml
-├── config/
-│   ├── odoo/
-│   │   ├── odoo.conf
-│   │   └── requirements.txt
-│   └── logrotate/
-│       └── odoo
-├── resources/
-│   └── odoo/
-│       └── entrypoint.sh
-├── moo
-├── scripts/
-├── odoo/
-│   └── custom/
-│       └── src/
-│           └── private/
+        ? options.sourceRepos
+            .map((repo, index) => {
+            const connector = index === options.sourceRepos.length - 1 ? '└──' : '├──';
+            return `│       │   │   ${connector} ${repo.path}/              # Project-owned addon source repository`;
+        })
+            .join('\n')
+        : '│       │   │   └── (add project-owned repos with ./moo add-repo)';
+    return `${options.devRepo}/                          # Development environment root
+├── compose.yaml                            # Base Docker Compose file
+├── compose/                                # Compose overlays for each workflow
+│   ├── dev.yaml                            # Local development services
+│   ├── debug.yaml                          # Debug tooling and debug-friendly settings
+│   ├── test.yaml                           # Test runner services and test database setup
+│   ├── stage.yaml                          # Staging-like deployment overlay
+│   ├── prod.yaml                           # Production deployment overlay
+│   ├── proxy.yaml                          # Reverse proxy / edge routing overlay
+│   └── tools.yaml                          # Optional maintenance and helper tools
+├── config/                                 # Runtime configuration mounted into containers
+│   ├── odoo/                               # Odoo server configuration
+│   │   ├── odoo.conf                       # Main Odoo configuration file
+│   │   └── requirements.txt                # Extra Python dependencies for the Odoo container
+│   └── logrotate/                          # Log rotation configuration
+│       └── odoo                            # Logrotate rules for Odoo logs
+├── resources/                              # Container-side helper resources
+│   └── odoo/                               # Resources specific to the Odoo service
+│       └── entrypoint.sh                   # Container startup script that discovers addons
+├── moo                                     # Local command hub shortcut
+├── scripts/                                # Shell scripts used by the local command hub
+├── odoo/                                   # Odoo workspace data and custom source tree
+│   └── custom/                             # Custom addon layer for this environment
+│       ├── src/                            # Source repository checkout root
+│       │   ├── private/                    # Project-owned/private addon repositories
 ${sourceRepoRows}
-├── docs/
-│   ├── appstore-release.md
-│   └── compose.md
-├── .env.example
-├── README.md
-└── AGENTS.md`;
+│       │   ├── oca/                        # OCA addon repositories
+│       │   └── external/                   # Non-OCA third-party addon repositories
+│       ├── patches/                        # Local patches for upstream repositories
+│       └── manifests/                      # Source manifests, locks, and pinned revisions
+├── docs/                                   # Project-specific documentation
+│   ├── appstore-release.md                 # Odoo App Store release checklist and notes
+│   └── compose.md                          # Compose layout and operations reference
+├── .env.example                            # Template for local environment variables
+├── README.md                               # This environment overview
+└── AGENTS.md                               # Agent instructions for this environment`;
 }
 function sourceRepoDocs(options) {
     if (!hasSourceRepos(options)) {
         return `This environment was scaffolded without source repository submodules.
 Add source repositories later from the cockpit or with \`npx @wpmoo/odoo add-repo\`.
-They will be added under \`odoo/custom/src/private\`.`;
+They can be organized under:
+
+\`odoo/custom/src/private\` for project-owned/private addon repositories,
+\`odoo/custom/src/oca\` for OCA repositories, and
+\`odoo/custom/src/external\` for non-OCA third-party repositories.
+
+Pinned external manifests and local patches should live under
+\`odoo/custom/manifests\` and \`odoo/custom/patches\` respectively.`;
     }
     return options.sourceRepos
         .map((repo) => `### ${repo.path}
@@ -78,6 +94,9 @@ Submodule path:
 odoo/custom/src/private/${repo.path}
 \`\`\`
 
+Note: If this repository is an OCA or third-party source, place it under
+\`odoo/custom/src/oca\` or \`odoo/custom/src/external\` according to your policy.
+
 Expected addon layout:
 
 \`\`\`text
@@ -154,7 +173,7 @@ function environmentKind() {
     return 'Docker Compose';
 }
 function repoDuplicationNote() {
-    return 'Keep these repositories under `odoo/custom/src/private`; the Compose entrypoint exposes discovered addons through `/mnt/wpmoo-addons`.';
+    return 'Keep source repositories under the relevant source directory (`private`, `oca`, or `external`); the Compose entrypoint exposes discovered addons through `/mnt/wpmoo-addons`.';
 }
 function verificationCommand(options) {
     const firstAddon = allAddons(options)[0] ?? options.product;
@@ -180,7 +199,8 @@ Set WPMOO_ENV=stage or WPMOO_ENV=prod only after providing production-grade secr
 If copied from the standalone resource, additional compose notes are in
 \`docs/compose.md\`.
 
-Source repositories stay under \`odoo/custom/src/private\` when configured. At
+Source repositories stay under \`odoo/custom/src/{private,oca,external}\` when
+configured. At
 container startup, \`entrypoint.sh\` scans those repositories for addons and
 exposes them through \`/mnt/wpmoo-addons\`.
 
@@ -553,7 +573,8 @@ export function renderReadme(options) {
 Private ${environmentKind()} development environment for the ${title} product.
 
 This folder owns the development environment only. Product source code lives
-in source repository submodules under \`odoo/custom/src/private\` when source
+in source repository submodules under \`odoo/custom/src/private\`,
+\`odoo/custom/src/oca\`, or \`odoo/custom/src/external\` when source
 repositories are connected.
 
 ## Repository Layout
@@ -603,7 +624,8 @@ export function renderAgents(options) {
         ? options.sourceRepos.map((repo) => `- \`${repo.path}\`: \`${repo.url}\``).join('\n')
         : '- No source repositories are configured yet.';
     const sourceLayout = hasSourceRepos(options)
-        ? `Product repositories are Git submodules:
+        ? `Product repositories are Git submodules. They are listed under the private
+source directory below for this environment:
 
 \`\`\`text
 ${options.sourceRepos.map((repo) => `odoo/custom/src/private/${repo.path}`).join('\n')}

package/docs/generated-environment-verification.md

@@ -21,9 +21,10 @@ not validate staging or production deployments.
 | Compose resource files | Compact compose layout is present (`compose.yaml` + environment overlays under `compose/`), plus config/resources/scripts. | `npx @wpmoo/odoo create ...` |
 | `./moo` delegation | `./moo` dispatches fixed daily actions to the matching script and preserves argument pass-through. | `./moo <action> ...` |
 | Doctor checks | Metadata, compose files, scripts, source repo paths, and local tooling checks behave as expected. | `npx @wpmoo/odoo doctor` or `./moo doctor` |
+| Generated Postgres checks | For PostgreSQL 18 environments, doctor validates db mount targets avoid old PG image-specific paths. | `npx @wpmoo/odoo doctor` |
 | Source repo add/remove | Source repository registration and submodule lifecycle behave correctly. | `npx @wpmoo/odoo add-repo ...`, `npx @wpmoo/odoo remove-repo ...` |
 | Module add/remove | Module registration changes are applied to the selected source repo config. | `npx @wpmoo/odoo add-module ...`, `npx @wpmoo/odoo remove-module ...` |
-| Safe reset | Generated files are refreshed without deleting source module code. Legacy user-editable paths from older templates may remain and are reported for manual cleanup. | `npx @wpmoo/odoo reset` |
+| 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/odoo reset` |
 | Snapshot/restore and lint/pot | These actions are delegated by `./moo` to compose scripts without extra package-side logic. | `./moo snapshot ...`, `./moo restore-snapshot ...`, `./moo lint`, `./moo pot ...` |
 
 ## Compact compose checks
@@ -43,6 +44,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.
 
+For PostgreSQL 18 environments (including `POSTGRES_IMAGE=postgres:18`), ensure db
+volume and tmpfs mount targets use `/var/lib/postgresql` directly:
+
+```text
+- volumes:
+  - db_data:/var/lib/postgresql
+```
+
+Paths such as `/var/lib/postgresql/data` and `/var/lib/postgresql/18/docker` are
+no longer accepted by the package `doctor` check.
+
 ## Safe reset policy
 
 Safe reset intentionally avoids deleting user-editable legacy paths from old
@@ -54,6 +66,19 @@ test/
 .github/
 ```
 
+In addition, safe reset preserves local runtime and source-data state while refreshing
+generated and compose assets:
+
+```text
+.env
+data/
+backups/
+odoo/custom/src/oca/
+odoo/custom/src/external/
+odoo/custom/patches/
+odoo/custom/manifests/
+```
+
 ## Local verification commands
 
 Run from the `wpmoo-odoo` repository root:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpmoo/odoo",
-  "version": "0.8.57",
+  "version": "0.8.59",
   "description": "WPMoo Odoo lifecycle tooling for development, staging, and production workflows.",
   "type": "module",
   "repository": {