@wpmoo/odoo 0.8.59 → 0.8.60

package/README.md

@@ -296,6 +296,34 @@ npx @wpmoo/odoo remove-repo --repo odoo_sample_module_reports
 
 WPMoo refuses to remove a source repo submodule when that submodule has uncommitted changes.
 
+Generated environments also keep a deterministic source manifest at
+`odoo/custom/manifests/sources.yaml`. It mirrors source submodules from
+`.wpmoo/odoo.json` and `.gitmodules`, including source type, path, URL, branch,
+and addon boundaries.
+
+Inspect configured sources:
+
+```bash
+npx @wpmoo/odoo source list
+```
+
+Regenerate the manifest and metadata from the current metadata/gitmodule state:
+
+```bash
+npx @wpmoo/odoo source sync
+```
+
+`source add` and `source remove` are direct aliases for the same repository
+operations:
+
+```bash
+npx @wpmoo/odoo source add \
+  --repo-url https://github.com/OCA/server-tools.git \
+  --source-type oca
+
+npx @wpmoo/odoo source remove --repo server-tools --source-type oca
+```
+
 ## Status, Doctor, and Recovery
 
 `status` is fast and offline. It reads local metadata and files only:
@@ -313,9 +341,10 @@ npx @wpmoo/odoo doctor
 ```
 
 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`).
+source manifest consistency, 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:
 

package/dist/args.js

@@ -12,6 +12,7 @@ const commandNames = new Set([
     'remove-repo',
     'add-module',
     'remove-module',
+    'source',
     'reset',
     'doctor',
     ...dailyActionCommands,

package/dist/cli.js

@@ -22,6 +22,7 @@ import { promptRepositoryUrl } from './prompt-repositories.js';
 import { inferGitHubOwner, inferRepoPath, normalizeRepositoryUrl } from './repo-url.js';
 import { addModuleRepo, listModuleRepos, removeModuleRepo } from './repo-actions.js';
 import { renderSafeResetPreview, safeResetEnvironment } from './safe-reset.js';
+import { listSources, renderSourceList, syncSources } from './source-actions.js';
 import { checkGitHubRepositories, createGitHubRepositories, manualCreateCommands, repositoryPreflightAvailable, } from './repository-preflight.js';
 import { scaffold } from './scaffold.js';
 import { renderBanner } from './templates.js';
@@ -470,6 +471,60 @@ function resetOptionsFromArgs(argv) {
         stage: booleanOption(values, 'stage', true),
     };
 }
+function sourceUsage() {
+    return 'Usage: wpmoo source <list|sync|add|remove> [options]';
+}
+function sourceSyncOptionsFromArgs(argv) {
+    const { values } = parseArgs(argv);
+    return {
+        target: resolve(stringOption(values, 'target') ?? process.cwd()),
+        stage: booleanOption(values, 'stage', true),
+    };
+}
+function sourceListTargetFromArgs(argv) {
+    const { values } = parseArgs(argv);
+    return resolve(stringOption(values, 'target') ?? process.cwd());
+}
+async function runSourceCommand(argv) {
+    const [subcommand, ...subcommandArgv] = argv;
+    if (!subcommand) {
+        throw new Error(sourceUsage());
+    }
+    if (subcommand === 'list') {
+        console.log(renderBanner());
+        const target = sourceListTargetFromArgs(subcommandArgv);
+        console.log(renderSourceList(await listSources(target)));
+        return;
+    }
+    if (subcommand === 'sync') {
+        console.log(renderBanner());
+        const options = sourceSyncOptionsFromArgs(subcommandArgv);
+        await syncSources(options);
+        outro(`Synced source manifest in ${options.target}.`);
+        return;
+    }
+    if (subcommand === 'add') {
+        const options = await addRepoOptionsFromArgs(subcommandArgv);
+        if (!options) {
+            throw new Error('Usage: wpmoo source add --repo-url <url> [--source-type private|oca|external]');
+        }
+        console.log(renderBanner());
+        await addModuleRepo(options);
+        outro(`Added source repo under ${renderedSourceRepoPath(options.target, options.sourceType ?? 'private', options.repoPath)}.`);
+        return;
+    }
+    if (subcommand === 'remove') {
+        const options = removeRepoOptionsFromArgs(subcommandArgv);
+        if (!options) {
+            throw new Error('Usage: wpmoo source remove --repo <name> [--source-type private|oca|external]');
+        }
+        console.log(renderBanner());
+        await removeModuleRepo(options);
+        outro(`Removed source repo ${options.repoPath} from ${options.target}.`);
+        return;
+    }
+    throw new Error(sourceUsage());
+}
 async function confirmSafeResetFromMenu(options) {
     note(renderSafeResetPreview(options.target, options.stage), 'Safe reset preview');
     const confirmed = await confirm({
@@ -770,6 +825,10 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
         outro(`Removed source repo ${promptedOptions.repoPath} from ${promptedOptions.target}.`);
         return;
     }
+    if (route.command === 'source') {
+        await runSourceCommand(route.argv);
+        return;
+    }
     if (route.command === 'add-module') {
         const options = await addModuleOptionsFromArgs(route.argv);
         if (options) {

package/dist/doctor.js

@@ -5,6 +5,7 @@ import { detectComposeLayout, readEnvFile, selectedComposeEnvironment } from './
 import { dailyActionScripts } from './daily-actions.js';
 import { defaultPostgresVersion } from './external-templates.js';
 import { defaultOdooVersion, markerPath } from './environment.js';
+import { listGitmoduleSources, readSourceManifest, sourceManifestPath, } from './source-manifest.js';
 const realCommandRunner = async (command, args, options) => {
     const result = await execa(command, args, { cwd: options.cwd });
     return { stdout: result.stdout, stderr: result.stderr };
@@ -88,19 +89,42 @@ function inferPostgresVersion(metadata, odooVersion, env) {
     }
     return defaultPostgresVersion(odooVersion);
 }
+function normalizeSourceType(value) {
+    if (value === 'oca' || value === 'external' || value === 'private') {
+        return value;
+    }
+    return 'private';
+}
+function sourceRepoPath(type, path) {
+    return `odoo/custom/src/${type}/${path}`;
+}
+function entryKey(type, path) {
+    return `${type}:${path}`;
+}
 function sourceReposFromMetadata(metadata) {
     const sourceRepos = metadata.sourceRepos;
     if (!Array.isArray(sourceRepos))
         return [];
-    return sourceRepos.map((repo, index) => {
+    return sourceRepos
+        .map((repo, index) => {
         if (!isRecord(repo) || typeof repo.path !== 'string' || !repo.path.trim()) {
             throw new Error(`Invalid sourceRepos entry in .wpmoo/odoo.json at index ${index}`);
         }
         return {
             url: typeof repo.url === 'string' ? repo.url : '',
             path: repo.path.trim(),
-            addons: Array.isArray(repo.addons) ? repo.addons.filter((addon) => typeof addon === 'string') : [],
+            addons: Array.isArray(repo.addons)
+                ? repo.addons.filter((addon) => typeof addon === 'string')
+                : [],
+            sourceType: normalizeSourceType(repo.sourceType),
         };
+    })
+        .filter((repo) => repo.path)
+        .sort((left, right) => {
+        const typeOrder = left.sourceType.localeCompare(right.sourceType);
+        if (typeOrder !== 0)
+            return typeOrder;
+        return left.path.localeCompare(right.path);
     });
 }
 async function readMetadata(target) {
@@ -141,7 +165,7 @@ function isNotGitCheckoutError(error) {
 }
 function isSourceRepoSubmodule(path, sourceRepos) {
     return sourceRepos.some((repo) => {
-        const sourcePath = `odoo/custom/src/private/${repo.path}`;
+        const sourcePath = sourceRepoPath(repo.sourceType ?? 'private', repo.path);
         return path === sourcePath || path.startsWith(`${sourcePath}/`);
     });
 }
@@ -165,6 +189,47 @@ function sourceSubmoduleStatusErrors(output, sourceRepos) {
     }
     return errors;
 }
+function manifestEntryToKey(entry) {
+    return entryKey(entry.type, entry.path);
+}
+function manifestRepoToKey(repo) {
+    return entryKey(normalizeSourceType(repo.sourceType), repo.path);
+}
+function formatKeyForPath(key) {
+    const [sourceType, ...pathParts] = key.split(':');
+    return sourceRepoPath(sourceType, pathParts.join(':'));
+}
+function checkSourceConsistency(sourceRepos, manifestEntries, gitmoduleSources, manifestExists) {
+    if (!manifestExists) {
+        return [];
+    }
+    const errors = [];
+    const metadataEntries = new Map();
+    for (const repo of sourceRepos) {
+        metadataEntries.set(manifestRepoToKey(repo), repo);
+    }
+    const manifestMap = new Map();
+    for (const entry of manifestEntries) {
+        manifestMap.set(manifestEntryToKey(entry), entry);
+    }
+    const gitmoduleSet = new Set(gitmoduleSources.map((source) => manifestEntryToKey({ type: source.type, path: source.path })));
+    const sortedMetadataKeys = [...metadataEntries.keys()].sort();
+    const sortedManifestKeys = [...manifestMap.keys()].sort();
+    for (const key of sortedMetadataKeys) {
+        if (!manifestMap.has(key)) {
+            errors.push(`Metadata source entry missing in manifest: ${formatKeyForPath(key)}`);
+        }
+    }
+    for (const key of sortedManifestKeys) {
+        if (!metadataEntries.has(key)) {
+            errors.push(`Manifest source entry missing in metadata: ${formatKeyForPath(key)}`);
+        }
+        if (!gitmoduleSet.has(key)) {
+            errors.push(`Manifest source path missing in .gitmodules: ${formatKeyForPath(key)}`);
+        }
+    }
+    return errors;
+}
 export async function runDoctor(target = process.cwd(), runner = realCommandRunner) {
     const lines = ['WPMoo doctor'];
     const errors = [];
@@ -227,12 +292,27 @@ export async function runDoctor(target = process.cwd(), runner = realCommandRunn
     }
     const sourceRepos = sourceReposFromMetadata(metadata);
     for (const repo of sourceRepos) {
-        const relativePath = `odoo/custom/src/private/${repo.path}`;
-        if (!(await exists(join(target, relativePath)))) {
+        const relativePath = sourceRepoPath(normalizeSourceType(repo.sourceType), repo.path);
+        if (!(await exists(join(target, relativePath))) && repo.path) {
             errors.push(`Missing source repo path: ${relativePath}`);
         }
     }
     lines.push(`OK source repos ${sourceRepos.length} checked`);
+    const manifestPath = join(target, sourceManifestPath);
+    const hasManifest = await exists(manifestPath);
+    let manifestEntries = [];
+    if (hasManifest) {
+        try {
+            manifestEntries = (await readSourceManifest(target)).sources;
+        }
+        catch (error) {
+            errors.push(`Failed to read source manifest ${sourceManifestPath}: ${errorMessage(error)}`);
+        }
+    }
+    const gitmoduleSources = await listGitmoduleSources(target);
+    if (errors.length === 0 || manifestEntries.length > 0) {
+        errors.push(...checkSourceConsistency(sourceRepos, manifestEntries, gitmoduleSources, hasManifest));
+    }
     if (env) {
         const httpPort = validatePort('HTTP_PORT', env, errors);
         const geventPort = validatePort('GEVENT_PORT', env, errors);

package/dist/environment.js

@@ -48,7 +48,7 @@ function normalizeMetadataSourceRepo(repo) {
     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) {
+    if (!path) {
         return undefined;
     }
     return { ...candidate, path, url, addons, sourceType };
@@ -84,13 +84,20 @@ export async function readEnvironmentMetadata(target) {
         return undefined;
     }
 }
-async function writeEnvironmentMetadata(target, metadata) {
+export 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 replaceSourceRepos(target, sourceRepos) {
+    const metadata = await readEnvironmentMetadata(target);
+    if (!metadata)
+        return;
+    metadata.sourceRepos = withoutPathDuplicates(sourceRepos.map((repo) => sourceRepoWithType(repo)));
+    await writeEnvironmentMetadata(target, metadata);
+}
 export async function upsertSourceRepoMetadata(target, sourceRepo) {
     const metadata = await readEnvironmentMetadata(target);
     if (!metadata)

package/dist/help.js

@@ -9,6 +9,10 @@ Usage:
   npx @wpmoo/odoo status
   npx @wpmoo/odoo add-repo --repo-url <url> [--source-type private|oca|external]
   npx @wpmoo/odoo remove-repo --repo <name>
+  npx @wpmoo/odoo source list
+  npx @wpmoo/odoo source sync
+  npx @wpmoo/odoo source add --repo-url <url> [--source-type private|oca|external]
+  npx @wpmoo/odoo source remove --repo <name> [--source-type private|oca|external]
   npx @wpmoo/odoo add-module --repo <source-repo> --module <module-name>
   npx @wpmoo/odoo remove-module --repo <source-repo> --module <module-name>
   npx @wpmoo/odoo reset
@@ -92,6 +96,9 @@ Task recipes:
     npx @wpmoo/odoo
   Add source repo:
     npx @wpmoo/odoo add-repo --repo-url <url> --source-type oca
+  Inspect and sync source manifest:
+    npx @wpmoo/odoo source list
+    npx @wpmoo/odoo source sync
   Add module:
     npx @wpmoo/odoo add-module --repo <source-repo> --module <module-name>
   Run tests:

package/dist/repo-actions.js

@@ -5,6 +5,7 @@ import { readEnvironmentMetadata, removeSourceRepoMetadata, upsertSourceRepoMeta
 import { ensureRemoteHasBranch, ensureSubmodule, hasUncommittedChanges, realGit, removeSubmodule, stageAll, } from './git.js';
 import { isValidPathSegment, validateRepoPath } from './path-validation.js';
 import { inferRepoPath } from './repo-url.js';
+import { removeSourceManifestEntry, upsertSourceManifestEntry } from './source-manifest.js';
 export const addonsYamlHeader = `# Addons activated from source submodules.
 #
 # Source repos are managed as Git submodules under odoo/custom/src/private (product code).
@@ -106,6 +107,13 @@ export async function addModuleRepo(options, git = realGit) {
         addons: [repoPath],
         sourceType,
     });
+    await upsertSourceManifestEntry(options.target, {
+        type: sourceType,
+        path: repoPath,
+        url: options.repoUrl,
+        branch: options.odooVersion,
+        addons: [repoPath],
+    });
     if (!(await isComposeEnvironment(options.target))) {
         const addonsYaml = await readAddonsYaml(options.target);
         if (sourceType === 'private') {
@@ -134,6 +142,9 @@ export async function removeModuleRepo(options, git = realGit) {
     }
     await removeSubmodule(git, options.target, submodulePath);
     await removeSourceRepoMetadata(options.target, repoPath, resolvedSourceType);
+    if (resolvedSourceType) {
+        await removeSourceManifestEntry(options.target, resolvedSourceType, repoPath);
+    }
     if (!(await isComposeEnvironment(options.target))) {
         const addonsYaml = await readAddonsYaml(options.target);
         if (resolvedSourceType === 'private') {

package/dist/safe-reset.js

@@ -5,8 +5,9 @@ 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 { readAddonsYaml } from './repo-actions.js';
 import { generatedFiles } from './scaffold.js';
+import { listGitmoduleSources } from './source-manifest.js';
 const safeResetProtectedPaths = [
     'data',
     'backups',
@@ -109,18 +110,18 @@ function parseRepoPathsFromAddonsYaml(addonsYaml) {
         .filter((repoPath) => repoPath && isValidPathSegment(repoPath))
         .map(validateRepoPath);
 }
-async function readSubmoduleUrl(target, repoPath) {
+async function readSubmoduleUrl(target, repoPath, sourceType) {
     const safeRepoPath = validateRepoPath(repoPath);
     try {
         const gitmodules = await readFile(join(target, '.gitmodules'), 'utf8');
-        const escapedPath = `odoo/custom/src/private/${safeRepoPath}`;
+        const escapedPath = `odoo/custom/src/${sourceType}/${safeRepoPath}`;
         const sections = gitmodules.split(/\n(?=\[submodule )/);
         const section = sections.find((value) => value.includes(`path = ${escapedPath}`));
         const url = section?.match(/^\s*url\s*=\s*(.+)$/m)?.[1]?.trim();
-        return url || `odoo/custom/src/private/${safeRepoPath}`;
+        return url || `odoo/custom/src/${sourceType}/${safeRepoPath}`;
     }
     catch {
-        return `odoo/custom/src/private/${safeRepoPath}`;
+        return `odoo/custom/src/${sourceType}/${safeRepoPath}`;
     }
 }
 async function pathExists(path) {
@@ -135,18 +136,33 @@ async function pathExists(path) {
 async function inferOptions(target) {
     const metadata = await readEnvironmentMetadata(target);
     const addonsYaml = await readAddonsYaml(target);
-    const moduleRepos = await listModuleRepos(target);
+    const gitmoduleSources = await listGitmoduleSources(target);
     const addonRepos = parseRepoPathsFromAddonsYaml(addonsYaml);
-    const metadataRepoPaths = metadata?.sourceRepos.map((repo) => repo.path).filter((repoPath) => isValidPathSegment(repoPath)).map(validateRepoPath) ??
-        [];
-    const repoPaths = [
-        ...new Set([...metadataRepoPaths, ...moduleRepos, ...addonRepos]),
-    ];
-    const product = metadata?.product ?? repoPaths[0] ?? titleFromTarget(target);
-    const sourceRepos = await Promise.all(repoPaths.map(async (repoPath) => ({
-        path: repoPath,
-        url: metadata?.sourceRepos.find((repo) => repo.path === repoPath)?.url ?? (await readSubmoduleUrl(target, repoPath)),
-        addons: parseAddonsForRepo(addonsYaml, repoPath),
+    const sourceByKey = new Map();
+    for (const repo of metadata?.sourceRepos ?? []) {
+        if (isValidPathSegment(repo.path)) {
+            const sourceType = repo.sourceType ?? 'private';
+            const path = validateRepoPath(repo.path);
+            sourceByKey.set(`${sourceType}:${path}`, { sourceType, path });
+        }
+    }
+    for (const repo of gitmoduleSources) {
+        sourceByKey.set(`${repo.type}:${repo.path}`, { sourceType: repo.type, path: repo.path });
+    }
+    for (const repoPath of addonRepos) {
+        sourceByKey.set(`private:${repoPath}`, { sourceType: 'private', path: repoPath });
+    }
+    const sourceLocations = [...sourceByKey.values()];
+    const product = metadata?.product ?? sourceLocations[0]?.path ?? titleFromTarget(target);
+    const sourceRepos = await Promise.all(sourceLocations.map(async ({ sourceType, path }) => ({
+        path,
+        sourceType,
+        url: metadata?.sourceRepos
+            .find((repo) => repo.path === path && (repo.sourceType ?? 'private') === sourceType)
+            ?.url.trim() ||
+            gitmoduleSources.find((repo) => repo.path === path && repo.type === sourceType)?.url ||
+            (await readSubmoduleUrl(target, path, sourceType)),
+        addons: parseAddonsForRepo(addonsYaml, path),
     })));
     return {
         product,

package/dist/scaffold.js

@@ -6,14 +6,19 @@ import { plannedExternalAssetOptions, renderComposeEnvExample } from './external
 import { cloneRepository, ensureSubmodule, ensureRemoteHasBranch, realGit, stageAll, syncSubmodules, } from './git.js';
 import { renderAgents, renderAppstoreRelease, renderGitignore, renderMooDelegationScript, renderPlaceholder, renderReadme, } from './templates.js';
 import { validateAddonName, validateRepoPath } from './path-validation.js';
+import { renderSourceManifest, sourceManifestEntriesFromMetadata } from './source-manifest.js';
 function validateSourceRepo(repo) {
     const path = validateRepoPath(repo.path);
     return {
         ...repo,
         path,
+        sourceType: repo.sourceType ?? 'private',
         addons: repo.addons.map(validateAddonName),
     };
 }
+function sourceRepoSubmodulePath(repo) {
+    return `odoo/custom/src/${repo.sourceType ?? 'private'}/${repo.path}`;
+}
 function validateScaffoldOptions(options) {
     return {
         ...options,
@@ -56,6 +61,10 @@ export function generatedFiles(options) {
         { path: 'README.md', content: renderReadme(safeOptions) },
         { path: 'AGENTS.md', content: renderAgents(safeOptions) },
         { path: 'docs/appstore-release.md', content: renderAppstoreRelease(safeOptions) },
+        {
+            path: 'odoo/custom/manifests/sources.yaml',
+            content: renderSourceManifest(sourceManifestEntriesFromMetadata(safeOptions.sourceRepos, safeOptions.odooVersion)),
+        },
     ];
     return [
         ...files,
@@ -113,7 +122,7 @@ export async function scaffold(options, git = realGit) {
     const externalAssets = plannedExternalAssetOptions(safeOptions);
     const plannedCommands = [
         ...externalAssets.map((assetOptions) => renderExternalAssetCommand(assetOptions)),
-        ...safeOptions.sourceRepos.map((repo) => `git submodule add -b ${safeOptions.odooVersion} ${repo.url} odoo/custom/src/private/${repo.path}`),
+        ...safeOptions.sourceRepos.map((repo) => `git submodule add -b ${safeOptions.odooVersion} ${repo.url} ${sourceRepoSubmodulePath(repo)}`),
     ];
     if (safeOptions.stage) {
         plannedCommands.push('git add .');
@@ -136,9 +145,9 @@ export async function scaffold(options, git = realGit) {
         for (const repo of safeOptions.sourceRepos) {
             await ensureRemoteHasBranch(git, safeOptions.target, repo.url, safeOptions.odooVersion, safeOptions.initEmptyRepos);
         }
-        await mkdir(join(safeOptions.target, 'odoo/custom/src/private'), { recursive: true });
         for (const repo of safeOptions.sourceRepos) {
-            await ensureSubmodule(git, safeOptions.target, repo.url, safeOptions.odooVersion, `odoo/custom/src/private/${repo.path}`);
+            await mkdir(join(safeOptions.target, 'odoo/custom/src', repo.sourceType ?? 'private'), { recursive: true });
+            await ensureSubmodule(git, safeOptions.target, repo.url, safeOptions.odooVersion, sourceRepoSubmodulePath(repo));
         }
         await syncSubmodules(git, safeOptions.target);
     }

package/dist/source-actions.js

@@ -0,0 +1,42 @@
+import { defaultOdooVersion, readEnvironmentMetadata, replaceSourceRepos } from './environment.js';
+import { realGit, stageAll } from './git.js';
+import { listGitmoduleSources, readSourceManifest, sourceManifestEntriesFromMetadata, sourceReposFromManifest, syncManifestFromMetadataAndGitmodules, writeSourceManifest, } from './source-manifest.js';
+export async function listSources(target) {
+    const metadata = await readEnvironmentMetadata(target);
+    const manifest = await readSourceManifest(target);
+    if (manifest.sources.length > 0) {
+        return manifest.sources;
+    }
+    if (metadata?.sourceRepos.length) {
+        return sourceManifestEntriesFromMetadata(metadata.sourceRepos, metadata.odooVersion);
+    }
+    return syncManifestFromMetadataAndGitmodules([], metadata?.odooVersion ?? defaultOdooVersion, await listGitmoduleSources(target));
+}
+export function renderSourceList(entries) {
+    if (entries.length === 0) {
+        return 'No source repositories configured.';
+    }
+    return entries
+        .map((entry) => {
+        const branch = entry.branch ? ` @ ${entry.branch}` : '';
+        const addons = entry.addons.length ? ` addons: ${entry.addons.join(', ')}` : '';
+        return `${entry.type}/${entry.path}${branch} -> ${entry.url}${addons}`;
+    })
+        .join('\n');
+}
+export async function syncSources(options, git = realGit) {
+    const metadata = await readEnvironmentMetadata(options.target);
+    const manifest = await readSourceManifest(options.target);
+    const gitmodules = await listGitmoduleSources(options.target);
+    const fallbackBranch = metadata?.odooVersion ?? defaultOdooVersion;
+    const baseRepos = metadata?.sourceRepos.length ? metadata.sourceRepos : sourceReposFromManifest(manifest.sources);
+    const entries = syncManifestFromMetadataAndGitmodules(baseRepos, fallbackBranch, gitmodules);
+    await writeSourceManifest(options.target, entries);
+    if (metadata) {
+        await replaceSourceRepos(options.target, sourceReposFromManifest(entries));
+    }
+    if (options.stage) {
+        await stageAll(git, options.target);
+    }
+    return entries;
+}

package/dist/source-manifest.js

@@ -0,0 +1,338 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isValidPathSegment, validateRepoPath } from './path-validation.js';
+const validSourceTypes = ['private', 'oca', 'external'];
+export const sourceManifestPath = 'odoo/custom/manifests/sources.yaml';
+function fail(message) {
+    throw new Error(`Invalid source manifest ${sourceManifestPath}: ${message}`);
+}
+export function normalizeSourceType(value) {
+    return validSourceTypes.includes(value) ? value : 'private';
+}
+function dedupeAndSort(entries) {
+    const uniqueByTypePath = new Map();
+    for (const entry of entries) {
+        uniqueByTypePath.set(`${entry.type}:${entry.path}`, entry);
+    }
+    return [...uniqueByTypePath.values()].sort((left, right) => {
+        const typeOrder = left.type.localeCompare(right.type);
+        if (typeOrder !== 0)
+            return typeOrder;
+        return left.path.localeCompare(right.path);
+    });
+}
+function stripInlineComment(raw) {
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let index = 0; index < raw.length; index += 1) {
+        const char = raw[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (char === "'" && !inDouble) {
+            inSingle = !inSingle;
+        }
+        else if (char === '"' && !inSingle) {
+            inDouble = !inDouble;
+        }
+        else if (char === '#' && !inSingle && !inDouble) {
+            return raw.slice(0, index).trimEnd();
+        }
+    }
+    return raw;
+}
+function parseScalar(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return '';
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return JSON.parse(trimmed);
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1).replace(/\\'/g, "'");
+    }
+    return trimmed;
+}
+function leadingSpaces(line) {
+    return line.length - line.trimStart().length;
+}
+function parseSourcesBlock(content) {
+    const lines = content.split(/\r?\n/).map((line, index) => ({
+        lineNumber: index + 1,
+        line: line.replace(/\t/g, '  '),
+        trimmedLine: line.replace(/\t/g, '  ').trim(),
+    }));
+    const sourcesKeywordLine = lines.find((line) => /^\s*sources\s*:\s*(?:\[[^\]]*\])?\s*$/.test(stripInlineComment(line.line)));
+    if (!sourcesKeywordLine) {
+        fail('Missing top-level sources entry.');
+    }
+    const rawSourcesValue = stripInlineComment(sourcesKeywordLine.line).replace(/^\s*sources\s*:\s*/, '');
+    if (rawSourcesValue === '[]') {
+        return { sources: [] };
+    }
+    if (rawSourcesValue && rawSourcesValue !== '') {
+        fail(`Unexpected non-list value on line ${sourcesKeywordLine.lineNumber}: sources`);
+    }
+    const sourceLines = lines.slice(sourcesKeywordLine.lineNumber);
+    const parsed = [];
+    let index = 0;
+    while (index < sourceLines.length) {
+        const headerLine = sourceLines[index];
+        const noCommentHeader = stripInlineComment(headerLine.line);
+        if (!noCommentHeader.trim()) {
+            index += 1;
+            continue;
+        }
+        const itemMatch = /^\s*-\s*type:\s*(.+)\s*$/.exec(noCommentHeader);
+        if (!itemMatch) {
+            index += 1;
+            continue;
+        }
+        const item = {
+            type: normalizeSourceType(parseScalar(itemMatch[1])),
+            path: '',
+            url: '',
+            addons: [],
+        };
+        index += 1;
+        while (index < sourceLines.length) {
+            const rawLine = sourceLines[index];
+            const noComment = stripInlineComment(rawLine.line);
+            const trimmed = noComment.trim();
+            if (!trimmed) {
+                index += 1;
+                continue;
+            }
+            if (/^\s*-\s*type:\s*/.test(noComment)) {
+                break;
+            }
+            const pathMatch = /^\s*path:\s*(.+)\s*$/.exec(noComment);
+            if (pathMatch) {
+                item.path = validateRepoPath(parseScalar(pathMatch[1]));
+                index += 1;
+                continue;
+            }
+            const urlMatch = /^\s*url:\s*(.+)\s*$/.exec(noComment);
+            if (urlMatch) {
+                item.url = parseScalar(urlMatch[1]);
+                index += 1;
+                continue;
+            }
+            const branchMatch = /^\s*branch:\s*(.+)\s*$/.exec(noComment);
+            if (branchMatch) {
+                item.branch = parseScalar(branchMatch[1]);
+                index += 1;
+                continue;
+            }
+            const addonsLine = /^\s*addons:\s*$/.exec(noComment);
+            if (addonsLine) {
+                const baseIndent = leadingSpaces(rawLine.line) + 2;
+                index += 1;
+                while (index < sourceLines.length) {
+                    const addonRaw = stripInlineComment(sourceLines[index].line);
+                    const addonTrimmed = addonRaw.trim();
+                    if (!addonTrimmed) {
+                        index += 1;
+                        continue;
+                    }
+                    const addonMatch = /^\s*-\s*(.+)\s*$/.exec(addonRaw);
+                    if (!addonMatch) {
+                        break;
+                    }
+                    if (leadingSpaces(addonRaw) < baseIndent) {
+                        break;
+                    }
+                    const addon = parseScalar(addonMatch[1]);
+                    if (addon) {
+                        item.addons.push(addon);
+                    }
+                    index += 1;
+                }
+                continue;
+            }
+            fail(`Unexpected source entry field on line ${rawLine.lineNumber}: ${trimmed}`);
+        }
+        if (!item.path) {
+            fail(`Manifest entry missing path at line ${headerLine.lineNumber}`);
+        }
+        if (!item.url) {
+            fail(`Manifest entry missing url for ${item.type}:${item.path} at line ${headerLine.lineNumber}`);
+        }
+        if (!isValidPathSegment(item.path)) {
+            fail(`Invalid manifest path at line ${headerLine.lineNumber}: ${item.path}`);
+        }
+        if (item.addons.length === 0) {
+            item.addons.push(item.path);
+        }
+        item.addons = [...new Set(item.addons.map((addon) => validateRepoPath(addon)))].sort();
+        parsed.push(item);
+    }
+    return { sources: dedupeAndSort(parsed.filter((entry) => isValidPathSegment(entry.path))) };
+}
+export async function readSourceManifest(target) {
+    try {
+        const content = await readFile(join(target, sourceManifestPath), 'utf8');
+        return parseSourcesBlock(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { sources: [] };
+        }
+        throw error;
+    }
+}
+function renderQuoted(value) {
+    return JSON.stringify(value);
+}
+export function renderSourceManifest(entries) {
+    const normalized = dedupeAndSort(entries).map((entry) => {
+        const addons = [...new Set(entry.addons.map((addon) => validateRepoPath(addon)))].sort();
+        return {
+            type: entry.type,
+            path: validateRepoPath(entry.path),
+            url: entry.url.trim(),
+            branch: entry.branch?.trim(),
+            addons: addons.length ? addons : [validateRepoPath(entry.path)],
+        };
+    });
+    if (normalized.length === 0) {
+        return 'sources: []\n';
+    }
+    const body = normalized
+        .map((entry) => {
+        const lines = [
+            `  - type: ${renderQuoted(entry.type)}`,
+            `    path: ${renderQuoted(entry.path)}`,
+            `    url: ${renderQuoted(entry.url)}`,
+        ];
+        lines.push(`    branch: ${renderQuoted(entry.branch ?? '')}`);
+        lines.push('    addons:');
+        for (const addon of entry.addons) {
+            lines.push(`      - ${renderQuoted(addon)}`);
+        }
+        return lines.join('\n');
+    })
+        .join('\n');
+    return `sources:\n${body}\n`;
+}
+export async function writeSourceManifest(target, entries) {
+    const content = renderSourceManifest(entries);
+    const path = join(target, sourceManifestPath);
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, content, 'utf8');
+}
+function entryKey(type, path) {
+    return `${type}:${path}`;
+}
+export async function upsertSourceManifestEntry(target, entry) {
+    const manifest = await readSourceManifest(target);
+    const normalized = {
+        ...entry,
+        type: normalizeSourceType(entry.type),
+        path: validateRepoPath(entry.path),
+    };
+    const next = dedupeAndSort(manifest.sources.filter((current) => entryKey(current.type, current.path) !== entryKey(normalized.type, normalized.path)));
+    next.push(normalized);
+    await writeSourceManifest(target, next);
+}
+export async function removeSourceManifestEntry(target, type, path) {
+    const manifest = await readSourceManifest(target);
+    const key = entryKey(normalizeSourceType(type), validateRepoPath(path));
+    const next = manifest.sources.filter((entry) => entryKey(entry.type, entry.path) !== key);
+    await writeSourceManifest(target, next);
+}
+export function sourceManifestEntriesFromMetadata(sourceRepos, fallbackBranch) {
+    return sourceRepos.map((repo) => ({
+        type: normalizeSourceType(repo.sourceType),
+        path: validateRepoPath(repo.path),
+        url: repo.url.trim(),
+        branch: fallbackBranch,
+        addons: repo.addons.length ? [...new Set(repo.addons.map((addon) => validateRepoPath(addon)))] : [validateRepoPath(repo.path)],
+    }));
+}
+export async function listGitmoduleSources(target) {
+    try {
+        const gitmodules = await readFile(join(target, '.gitmodules'), 'utf8');
+        const lines = gitmodules.split(/\r?\n/);
+        const locations = [];
+        const pathRegex = /^\s*path\s*=\s*odoo\/custom\/src\/(private|oca|external)\/(.+)\s*$/;
+        const urlRegex = /^\s*url\s*=\s*(.+)\s*$/;
+        let pending;
+        for (const line of lines) {
+            const parsedPath = line.match(pathRegex);
+            if (parsedPath) {
+                const sourceType = parsedPath[1];
+                const repoPath = parsedPath[2]?.trim() ?? '';
+                if (!repoPath || !isValidPathSegment(repoPath)) {
+                    pending = undefined;
+                    continue;
+                }
+                pending = {
+                    type: sourceType,
+                    path: validateRepoPath(repoPath),
+                    url: '',
+                };
+                continue;
+            }
+            const parsedUrl = line.match(urlRegex);
+            if (!parsedUrl || !pending) {
+                continue;
+            }
+            const url = parseScalar(parsedUrl[1]);
+            if (url) {
+                locations.push({ ...pending, url });
+            }
+            pending = undefined;
+        }
+        return locations;
+    }
+    catch {
+        return [];
+    }
+}
+export function syncManifestFromMetadataAndGitmodules(sourceRepos, fallbackBranch, gitmodules = []) {
+    const byGitmodule = new Map();
+    for (const location of gitmodules) {
+        byGitmodule.set(`${normalizeSourceType(location.type)}:${location.path}`, location);
+    }
+    const entries = [];
+    for (const repo of sourceRepos) {
+        const normalized = {
+            type: normalizeSourceType(repo.sourceType),
+            path: validateRepoPath(repo.path),
+            url: repo.url.trim() || byGitmodule.get(`${normalizeSourceType(repo.sourceType)}:${repo.path}`)?.url || '',
+            branch: fallbackBranch,
+            addons: repo.addons.map(validateRepoPath),
+        };
+        entries.push(normalized);
+    }
+    for (const location of gitmodules) {
+        const key = `${location.type}:${location.path}`;
+        if (entries.some((entry) => `${entry.type}:${entry.path}` === key)) {
+            continue;
+        }
+        entries.push({
+            type: location.type,
+            path: location.path,
+            url: location.url,
+            branch: fallbackBranch,
+            addons: [location.path],
+        });
+    }
+    return dedupeAndSort(entries);
+}
+export function sourceReposFromManifest(entries) {
+    const normalized = dedupeAndSort(entries);
+    return normalized.map((entry) => ({
+        sourceType: entry.type,
+        path: validateRepoPath(entry.path),
+        url: entry.url,
+        addons: entry.addons.length ? [...new Set(entry.addons.map((addon) => validateRepoPath(addon)))] : [validateRepoPath(entry.path)],
+    }));
+}

package/dist/templates.js

@@ -20,6 +20,12 @@ function allAddons(options) {
 function hasSourceRepos(options) {
     return options.sourceRepos.length > 0;
 }
+function sourceTypeOf(repo) {
+    return repo.sourceType ?? 'private';
+}
+function sourceRepoRelativePath(repo) {
+    return `odoo/custom/src/${sourceTypeOf(repo)}/${repo.path}`;
+}
 function repositoryLayout(options) {
     const sourceRepoRows = hasSourceRepos(options)
         ? options.sourceRepos
@@ -91,11 +97,14 @@ ${repo.url}
 Submodule path:
 
 \`\`\`text
-odoo/custom/src/private/${repo.path}
+${sourceRepoRelativePath(repo)}
 \`\`\`
 
-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.
+Source manifest entry:
+
+\`\`\`text
+odoo/custom/manifests/sources.yaml
+\`\`\`
 
 Expected addon layout:
 
@@ -542,7 +551,7 @@ export function renderAddonsYaml(options) {
 # Source repos are managed as Git submodules under odoo/custom/src/private.
 # Do not duplicate these same repos in repos.yaml.
 
-${options.sourceRepos.map((repo) => `private/${repo.path}:\n${yamlList(repo.addons)}`).join('\n\n')}
+${options.sourceRepos.map((repo) => `${sourceTypeOf(repo)}/${repo.path}:\n${yamlList(repo.addons)}`).join('\n\n')}
 `;
 }
 export function renderReposYaml(options) {
@@ -551,7 +560,7 @@ export function renderReposYaml(options) {
 # Project source repositories are intentionally not listed here because
 # they are pinned as Git submodules:
 #
-${options.sourceRepos.map((repo) => `# - private/${repo.path}`).join('\n')}
+${options.sourceRepos.map((repo) => `# - ${sourceTypeOf(repo)}/${repo.path}`).join('\n')}
 #
 # Keep this file for upstream/OCA repositories that should be aggregated.
 
@@ -628,7 +637,7 @@ export function renderAgents(options) {
 source directory below for this environment:
 
 \`\`\`text
-${options.sourceRepos.map((repo) => `odoo/custom/src/private/${repo.path}`).join('\n')}
+${options.sourceRepos.map(sourceRepoRelativePath).join('\n')}
 \`\`\`
 
 ${repoDuplicationNote()}`

package/docs/generated-environment-verification.md

@@ -23,6 +23,7 @@ not validate staging or production deployments.
 | 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 ...` |
+| Source manifest sync | Source repo metadata, `.gitmodules`, and `odoo/custom/manifests/sources.yaml` stay aligned. | `npx @wpmoo/odoo source list`, `npx @wpmoo/odoo source sync` |
 | 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 (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 ...` |
@@ -79,6 +80,28 @@ odoo/custom/patches/
 odoo/custom/manifests/
 ```
 
+## Source manifest checks
+
+Generated environments include `odoo/custom/manifests/sources.yaml`. The manifest
+records each source repository's type (`private`, `oca`, or `external`), path,
+URL, Odoo branch, and addon boundaries.
+
+Use `source list` to inspect the current manifest view:
+
+```bash
+npx @wpmoo/odoo source list
+```
+
+Use `source sync` after manual submodule or metadata repair to regenerate the
+manifest and normalize `.wpmoo/odoo.json` source entries:
+
+```bash
+npx @wpmoo/odoo source sync
+```
+
+`doctor` fails when manifest entries, metadata entries, and source submodule
+paths diverge.
+
 ## Local verification commands
 
 Run from the `wpmoo-odoo` repository root:

package/package.json

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