@cat-factory/integrations 0.77.3 → 0.77.5

package/dist/modules/environments/provision-detect.logic.js

@@ -1,3 +1,4 @@
+import { BudgetedRepoScanner, joinRepoPath } from '@cat-factory/kernel';
 import { parse as parseYaml, parseAllDocuments } from 'yaml';
 import { extractComposeProfiles, extractExternalNetworks, hasBuildDirective, } from '../compose/compose-environment.logic.js';
 import { RepoReadError } from './repo-read-error.js';
@@ -20,7 +21,7 @@ const COMPOSE_FILES = [
     'docker-compose.prod.yml',
     'docker-compose.dev.yaml',
     'docker-compose.dev.yml',
-    // A bare `dev.yml` base (the acme-main `docker/dev.yml` shape) — lowest priority so a
+    // A bare `dev.yml` base (the acme-monolith `docker/dev.yml` shape) — lowest priority so a
     // canonical name still wins, but recognized so a complex multi-file compose repo is detected
     // (its OS overrides `dev.<os>.override.yml` become recipe compose-file candidates).
     'dev.yaml',
@@ -30,6 +31,10 @@ const COMPOSE_FILES = [
 // it — so unlike the canonical `compose.*`/`docker-compose.*` names it is only accepted as a compose
 // file when it actually declares a `services:` map (an empty/absent one ⇒ it isn't a compose file).
 const AMBIGUOUS_COMPOSE_FILES = new Set(['dev.yaml', 'dev.yml']);
+// The built-in (canonical) compose names, as a Set for a cheap membership test. A convention-added
+// EXTRA name (not in here) is non-canonical, so — like the bare `dev.*` names — it is trusted as a
+// compose file only when it actually declares `services:` (see `findCompose`).
+const COMPOSE_FILE_SET = new Set(COMPOSE_FILES);
 // Directories (relative to the service root) a compose file commonly nests under, in addition to
 // the root itself. One `listDir` per entry (cheap membership test against COMPOSE_FILES).
 const COMPOSE_DIR_CANDIDATES = ['', 'deploy', 'docker', '.docker', 'compose'];
@@ -115,7 +120,7 @@ const ENV_EXAMPLE_FILES = ['.env.example', '.env.sample', '.env.template', '.env
 // intentionally SEQUENTIAL (not batched/parallel): the budget short-circuit and the "first present
 // name/dir wins" ordering both depend on deterministic, in-order accounting. In practice a real
 // repo resolves in a handful of reads well before the cap; the cap only bites on decoy-heavy repos,
-// where truncation is surfaced as a note (see `Scanner.exhausted`).
+// where truncation is surfaced as a note (see `BudgetedRepoScanner.exhausted`).
 const READ_BUDGET = 200;
 const MAX_IMAGES = 8;
 // ---- Slice 2: stack-recipe detection (compose repos) -----------------------------------------
@@ -165,22 +170,42 @@ const OS_OVERRIDE_RE = /^(.+?)\.(wsl|mac|macos|osx|linux|windows|win)(?:\.overri
 const MAKEFILE_NAMES = ['Makefile', 'makefile', 'GNUmakefile'];
 const JUSTFILE_NAMES = ['justfile', 'Justfile', '.justfile'];
 const TASKFILE_NAMES = ['Taskfile.yml', 'Taskfile.yaml', 'taskfile.yml', 'taskfile.yaml'];
-/** Join + normalize repo-relative path segments, collapsing `.`/`..` (resolves `../base` refs). */
-function joinPath(...parts) {
-    const segs = [];
-    for (const part of parts) {
-        if (!part)
-            continue;
-        for (const seg of part.split('/')) {
-            if (!seg || seg === '.')
-                continue;
-            if (seg === '..')
-                segs.pop();
-            else
-                segs.push(seg);
+// Monorepo "service container" dirs an env/config template commonly lives ONE LEVEL DOWN in
+// (`services/app/.env.dev.local-dist`, `apps/web/.env.example`). Scanned a single level deep by
+// `collectEnvFileTemplates` in addition to the root-level dirs, so a per-service template outside
+// the compose dir is still surfaced (the pilot's documented `services/app/` gap).
+const ENV_TEMPLATE_CONTAINER_DIRS = ['services', 'apps', 'packages'];
+/** Append `extras` after `base`, dropping any already present in `base` (base wins / stays first). */
+function withExtras(base, extras) {
+    if (!extras || extras.length === 0)
+        return [...base];
+    const seen = new Set(base);
+    const out = [...base];
+    for (const raw of extras) {
+        const value = raw.trim();
+        if (value && !seen.has(value)) {
+            seen.add(value);
+            out.push(value);
         }
     }
-    return segs.join('/');
+    return out;
+}
+/**
+ * The compose file names to try, canonical-first: the built-in {@link COMPOSE_FILES} then any
+ * deployment-supplied extras (lowest priority, so a canonical name still wins). The
+ * {@link AMBIGUOUS_COMPOSE_FILES} `services:`-required guard still applies to the bare `dev.*` names.
+ */
+function resolveComposeFileNames(conventions) {
+    return withExtras(COMPOSE_FILES, conventions?.composeFiles);
+}
+function resolveComposeDirs(conventions) {
+    return withExtras(COMPOSE_DIR_CANDIDATES, conventions?.composeDirs);
+}
+function resolveSeedDirs(conventions) {
+    return withExtras(SEED_DIRS, conventions?.seedDirs);
+}
+function resolveEnvTemplateDirs(conventions) {
+    return withExtras(ENV_TEMPLATE_DIR_CANDIDATES, conventions?.envTemplateDirs);
 }
 function isYamlFile(name) {
     return name.endsWith('.yaml') || name.endsWith('.yml');
@@ -215,92 +240,6 @@ function parseOne(content) {
         return null;
     }
 }
-/**
- * Stateful repo reader with a hard read budget so detection can't fan out without bound. Reads are
- * MEMOIZED per path: the compose + recipe passes list several dirs in common (the repo root is a
- * candidate for k8s roots, compose dirs, env-template dirs, and the repo-CLI scan), so caching keeps
- * each unique path to a single real round-trip and stops those overlaps from burning the budget. A
- * cache hit is free (no budget spend) and deterministic, so the "first present name/dir wins"
- * ordering and the budget short-circuit are unaffected.
- */
-class Scanner {
-    reader;
-    gitRef;
-    reads = 0;
-    firstFault;
-    fileCache = new Map();
-    dirCache = new Map();
-    constructor(reader, gitRef) {
-        this.reader = reader;
-        this.gitRef = gitRef;
-    }
-    /** True once the read budget was hit — the scan may have stopped short of the full repo. */
-    get exhausted() {
-        return this.reads >= READ_BUDGET;
-    }
-    /**
-     * The message of the FIRST genuine read fault the reader threw (auth/permission revoked, rate
-     * limit, transport/token-mint error), else `undefined`. A miss (absent path) is NOT a fault. The
-     * caller raises {@link RepoReadError} when it detected nothing AND this is set — so a truly
-     * unreadable repo surfaces an actionable error instead of a misleading "nothing found".
-     */
-    get readFault() {
-        return this.firstFault;
-    }
-    recordFault(err) {
-        if (this.firstFault === undefined) {
-            this.firstFault = err instanceof Error ? err.message : String(err);
-        }
-    }
-    async getFile(path) {
-        const cached = this.fileCache.get(path);
-        if (cached !== undefined)
-            return cached;
-        if (this.reads >= READ_BUDGET)
-            return null;
-        this.reads++;
-        let content = null;
-        try {
-            const file = await this.reader.getFile(path, this.gitRef);
-            content = file?.content ?? null;
-        }
-        catch (err) {
-            // A genuine read fault (non-404 — the reader turns 404 into null itself). Keep scanning
-            // best-effort (a transient fault mustn't lose a good result) but record it so an all-miss
-            // outcome can be reported as "couldn't read" rather than "nothing found".
-            this.recordFault(err);
-        }
-        this.fileCache.set(path, content);
-        return content;
-    }
-    /** Read the first present file among `names` in `dir`; returns its content + matched name. */
-    async getFirstFile(dir, names) {
-        for (const name of names) {
-            const content = await this.getFile(joinPath(dir, name));
-            if (content !== null)
-                return { name, content };
-        }
-        return null;
-    }
-    async listDir(path) {
-        const cached = this.dirCache.get(path);
-        if (cached !== undefined)
-            return cached;
-        if (this.reads >= READ_BUDGET)
-            return [];
-        this.reads++;
-        try {
-            const entries = await this.reader.listDirectory(path, this.gitRef);
-            this.dirCache.set(path, entries);
-            return entries;
-        }
-        catch (err) {
-            this.recordFault(err);
-            this.dirCache.set(path, []);
-            return [];
-        }
-    }
-}
 function emptyScan() {
     return {
         kinds: new Set(),
@@ -364,7 +303,7 @@ async function scanRawDir(scanner, dir, scan) {
     const entries = await scanner.listDir(dir);
     for (const entry of entries) {
         if (entry.type !== 'dir' && isYamlFile(entry.name)) {
-            const content = await scanner.getFile(joinPath(dir, entry.name));
+            const content = await scanner.getFile(joinRepoPath(dir, entry.name));
             if (content)
                 for (const doc of parseDocs(content))
                     scanManifestDoc(doc, scan);
@@ -417,7 +356,7 @@ async function walkKustomize(scanner, dir, scan, depth) {
         // Skip remote bases (URLs / git refs) — only local paths are checkout-free readable.
         if (ref.includes('://') || ref.startsWith('git@'))
             continue;
-        const refPath = joinPath(dir, ref);
+        const refPath = joinRepoPath(dir, ref);
         if (isYamlFile(ref)) {
             const content = await scanner.getFile(refPath);
             if (content)
@@ -462,7 +401,7 @@ async function evaluateK8sDir(scanner, dir, entries) {
     for (const entry of entries) {
         if (entry.type === 'dir' || !isYamlFile(entry.name))
             continue;
-        const content = await scanner.getFile(joinPath(dir, entry.name));
+        const content = await scanner.getFile(joinRepoPath(dir, entry.name));
         const looksLikeManifest = content !== null && parseDocs(content).some((d) => asString(d.kind) && asString(d.apiVersion));
         if (looksLikeManifest)
             return { dir, hasOverlays: false, hasKustomization: false };
@@ -487,7 +426,7 @@ async function collectKubernetesRoots(scanner, root) {
     for (const candidate of K8S_DIR_CANDIDATES) {
         if (found.length >= MAX_MANIFEST_ROOTS)
             break;
-        const dir = joinPath(root, candidate);
+        const dir = joinRepoPath(root, candidate);
         const entries = await scanner.listDir(dir);
         if (entries.length === 0)
             continue;
@@ -503,7 +442,7 @@ async function collectKubernetesRoots(scanner, root) {
                 break;
             if (entry.type !== 'dir' || !K8S_NESTED_SUBDIRS.includes(entry.name))
                 continue;
-            const nestedDir = joinPath(dir, entry.name);
+            const nestedDir = joinRepoPath(dir, entry.name);
             const nested = await evaluateK8sDir(scanner, nestedDir, await scanner.listDir(nestedDir));
             if (nested)
                 add(nested);
@@ -524,7 +463,7 @@ async function findServiceDeployCandidates(scanner, serviceBasename) {
         for (const entry of await scanner.listDir(deployRoot)) {
             if (entry.type !== 'dir')
                 continue;
-            const path = joinPath(deployRoot, entry.name);
+            const path = joinRepoPath(deployRoot, entry.name);
             if (seen.has(path))
                 continue;
             // Skip a child that is itself a shared-deploy root (e.g. `manifests/services`): it's a
@@ -551,24 +490,28 @@ async function findServiceDeployCandidates(scanner, serviceBasename) {
  * picker), external networks + profiles (for the recipe), and the containing dir's listing (for the
  * `-f` override family).
  */
-async function findCompose(scanner, root) {
-    for (const dir of COMPOSE_DIR_CANDIDATES) {
-        const dirPath = joinPath(root, dir);
+async function findCompose(scanner, root, conventions) {
+    const composeFileNames = resolveComposeFileNames(conventions);
+    for (const dir of resolveComposeDirs(conventions)) {
+        const dirPath = joinRepoPath(root, dir);
         const entries = await scanner.listDir(dirPath);
         if (entries.length === 0)
             continue;
         const names = new Set(entries.filter((e) => e.type !== 'dir').map((e) => e.name));
-        for (const candidate of COMPOSE_FILES) {
+        for (const candidate of composeFileNames) {
             if (!names.has(candidate))
                 continue;
-            const path = joinPath(dirPath, candidate);
+            const path = joinRepoPath(dirPath, candidate);
             const content = await scanner.getFile(path);
             const doc = content ? parseOne(content) : null;
             const servicesRecord = asRecord(doc?.services) ?? {};
             const services = Object.keys(servicesRecord);
-            // An ambiguous bare `dev.ya?ml` is only a compose file when it declares services; otherwise
-            // it's some other `dev.yml` (CLI/CI/Ansible config) and must not be detected as compose.
-            if (AMBIGUOUS_COMPOSE_FILES.has(candidate) && services.length === 0)
+            // An ambiguous bare `dev.ya?ml` — or ANY convention-added extra name, which is non-canonical
+            // by definition — is only a compose file when it declares services; otherwise it's some other
+            // YAML (CLI/CI/Ansible/app config) that merely matches the name and must not be detected as
+            // compose. Canonical `compose.*`/`docker-compose.*` names are trusted without this guard.
+            const requiresServices = AMBIGUOUS_COMPOSE_FILES.has(candidate) || !COMPOSE_FILE_SET.has(candidate);
+            if (requiresServices && services.length === 0)
                 continue;
             // Single source of truth with the provider's build-mode rejection: any service with a
             // `build:` means the stack builds from source, so build mode is required to provision it.
@@ -594,17 +537,17 @@ function rankOverlay(name) {
 /** Resolve the manifest source path + renderer + (when several) the overlay candidates. */
 async function resolveManifestSource(scanner, k8s) {
     if (k8s.hasOverlays) {
-        const overlaysDir = joinPath(k8s.dir, 'overlays');
+        const overlaysDir = joinRepoPath(k8s.dir, 'overlays');
         const overlays = (await scanner.listDir(overlaysDir)).filter((e) => e.type === 'dir');
         if (overlays.length > 0) {
             const ranked = [...overlays].sort((a, b) => rankOverlay(a.name) - rankOverlay(b.name));
             const chosen = ranked[0];
             const candidates = ranked.map((o) => ({
-                path: joinPath(overlaysDir, o.name),
+                path: joinRepoPath(overlaysDir, o.name),
                 name: o.name,
                 recommended: o.name === chosen.name,
             }));
-            const chosenPath = joinPath(overlaysDir, chosen.name);
+            const chosenPath = joinRepoPath(overlaysDir, chosen.name);
             const hasK = (await scanner.getFirstFile(chosenPath, KUSTOMIZATION_FILES)) !== null;
             return {
                 path: chosenPath,
@@ -685,8 +628,8 @@ async function inferHelmReleases(scanner, root, k8sDir) {
                         field: 'helmReleases',
                         confidence: 'low',
                         message: releases.length > 0
-                            ? `Proposed ${releases.length} helm release(s) from ${joinPath(dir, helmfile.name)}; review charts/versions before applying.${unpinned > 0 ? ` ${unpinned} release(s) had an unpinned version and were skipped.` : ''}`
-                            : `Found ${joinPath(dir, helmfile.name)} but its release versions aren't pinned — pin them to a semver to enable.`,
+                            ? `Proposed ${releases.length} helm release(s) from ${joinRepoPath(dir, helmfile.name)}; review charts/versions before applying.${unpinned > 0 ? ` ${unpinned} release(s) had an unpinned version and were skipped.` : ''}`
+                            : `Found ${joinRepoPath(dir, helmfile.name)} but its release versions aren't pinned — pin them to a semver to enable.`,
                     },
                 };
             }
@@ -706,8 +649,8 @@ async function inferHelmReleases(scanner, root, k8sDir) {
                         field: 'helmReleases',
                         confidence: 'low',
                         message: releases.length > 0
-                            ? `Proposed ${releases.length} helm release(s) from ${joinPath(dir, chart.name)} dependencies; review before applying.`
-                            : `Found ${joinPath(dir, chart.name)} dependencies but their versions aren't pinned to a semver.`,
+                            ? `Proposed ${releases.length} helm release(s) from ${joinRepoPath(dir, chart.name)} dependencies; review before applying.`
+                            : `Found ${joinRepoPath(dir, chart.name)} dependencies but their versions aren't pinned to a semver.`,
                     },
                 };
             }
@@ -778,7 +721,7 @@ function collectComposeFiles(compose) {
             continue;
         const os = overrideOsFor(entry.name, stem);
         if (os)
-            osOverrides.push({ path: joinPath(compose.dir, entry.name), name: entry.name, os });
+            osOverrides.push({ path: joinRepoPath(compose.dir, entry.name), name: entry.name, os });
         else if (isBaseOverride(entry.name, stem))
             baseOverrideNames.push(entry.name);
     }
@@ -786,7 +729,7 @@ function collectComposeFiles(compose) {
     if (osOverrides.length === 0 && baseOverrideNames.length === 0)
         return {};
     for (const name of baseOverrideNames.sort())
-        baseFiles.push(joinPath(compose.dir, name));
+        baseFiles.push(joinRepoPath(compose.dir, name));
     osOverrides.sort((a, b) => a.name.localeCompare(b.name));
     const composeFileCandidates = [
         ...baseFiles.map((path) => ({ path, name: path.split('/').pop() ?? path, recommended: true })),
@@ -823,14 +766,20 @@ function isConfigLikeName(target) {
  * Find committed env/config TEMPLATE files (`*-dist` / `*.example` / …) beside the compose file and
  * in the service root's common config dirs, and pair each with its gitignored target. Deduped by
  * target; bounded by `MAX_ENV_FILES`. These become `recipe.envFiles` — materialized before `up`.
+ *
+ * Scans, in order: the compose dir, the root-level config dirs (`ENV_TEMPLATE_DIR_CANDIDATES` +
+ * any deployment `conventions.envTemplateDirs`), then ONE LEVEL DOWN into the monorepo
+ * service-container dirs (`ENV_TEMPLATE_CONTAINER_DIRS` — `services/<svc>/`, `apps/<svc>/`), so a
+ * per-service template that lives outside the compose dir (the pilot's `services/app/.env.dev.local-dist`
+ * gap) is still surfaced. First template seen for a given target wins; the root-level dirs are scanned
+ * before the deeper container dirs so a root/compose-dir template takes precedence.
  */
-async function collectEnvFileTemplates(scanner, root, composeDir) {
-    const dirs = [
-        ...new Set([composeDir, ...ENV_TEMPLATE_DIR_CANDIDATES.map((d) => joinPath(root, d))]),
-    ];
+async function collectEnvFileTemplates(scanner, root, composeDir, conventions) {
     const pairs = [];
     const seenTargets = new Set();
-    for (const dir of dirs) {
+    const sorted = () => pairs.sort((a, b) => a.template.localeCompare(b.template));
+    // Scan one flat directory; returns true once MAX_ENV_FILES is reached (caller stops).
+    const scanDir = async (dir) => {
         // Sort by name so the dedup-by-target choice (first template seen wins) is deterministic
         // regardless of the reader's directory-listing order.
         const entries = [...(await scanner.listDir(dir))].sort((a, b) => a.name.localeCompare(b.name));
@@ -840,16 +789,38 @@ async function collectEnvFileTemplates(scanner, root, composeDir) {
             const target = deriveEnvTemplateTarget(entry.name);
             if (!target)
                 continue;
-            const targetPath = joinPath(dir, target);
+            const targetPath = joinRepoPath(dir, target);
             if (seenTargets.has(targetPath))
                 continue;
             seenTargets.add(targetPath);
-            pairs.push({ template: joinPath(dir, entry.name), target: targetPath });
+            pairs.push({ template: joinRepoPath(dir, entry.name), target: targetPath });
             if (pairs.length >= MAX_ENV_FILES)
-                return pairs.sort((a, b) => a.template.localeCompare(b.template));
+                return true;
+        }
+        return false;
+    };
+    const rootDirs = [
+        ...new Set([
+            composeDir,
+            ...resolveEnvTemplateDirs(conventions).map((d) => joinRepoPath(root, d)),
+        ]),
+    ];
+    for (const dir of rootDirs) {
+        if (await scanDir(dir))
+            return sorted();
+    }
+    // One level into monorepo service containers (`services/app/…`), children sorted for determinism.
+    for (const container of ENV_TEMPLATE_CONTAINER_DIRS) {
+        const containerDir = joinRepoPath(root, container);
+        const children = [...(await scanner.listDir(containerDir))]
+            .filter((e) => e.type === 'dir')
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const child of children) {
+            if (await scanDir(joinRepoPath(containerDir, child.name)))
+                return sorted();
         }
     }
-    return pairs.sort((a, b) => a.template.localeCompare(b.template));
+    return sorted();
 }
 // Whole-token matches (bounded by `^`/`$` or a non-letter — `-`, `_`, `.`, digits — so `pre` does
 // NOT match inside `compressed` and `data` DOES match inside `add_data`) for the seed-dump ranking.
@@ -872,22 +843,22 @@ function rankSeedDump(name) {
  * one into a `compose-exec` seed-import step (never auto-applied). The heuristically-fullest dump is
  * pre-selected.
  */
-async function collectSeedDumps(scanner, root) {
+async function collectSeedDumps(scanner, root, conventions) {
     const found = [];
     const seen = new Set();
     const addSql = (dir, name) => {
         if (!name.toLowerCase().endsWith('.sql'))
             return;
-        const path = joinPath(dir, name);
+        const path = joinRepoPath(dir, name);
         if (seen.has(path))
             return;
         seen.add(path);
         found.push({ path, name });
     };
-    for (const rel of SEED_DIRS) {
+    for (const rel of resolveSeedDirs(conventions)) {
         if (found.length >= MAX_SEED_DUMPS)
             break;
-        const dir = joinPath(root, rel);
+        const dir = joinRepoPath(root, rel);
         const entries = await scanner.listDir(dir);
         for (const entry of entries) {
             if (found.length >= MAX_SEED_DUMPS)
@@ -896,7 +867,7 @@ async function collectSeedDumps(scanner, root) {
                 // A `migrations`/`migration` child holds schema DDL, not seed data — never a seed dump.
                 if (/^migrations?$/i.test(entry.name))
                     continue;
-                const childDir = joinPath(dir, entry.name);
+                const childDir = joinRepoPath(dir, entry.name);
                 for (const child of await scanner.listDir(childDir)) {
                     if (child.type !== 'dir')
                         addSql(childDir, child.name);
@@ -935,7 +906,7 @@ async function detectRepoCliHint(scanner, root, rootEntries) {
     const fileNames = new Set(rootEntries.filter((e) => e.type !== 'dir').map((e) => e.name));
     const hasBin = rootEntries.some((e) => e.type === 'dir' && e.name === 'bin');
     if (hasBin) {
-        for (const entry of await scanner.listDir(joinPath(root, 'bin'))) {
+        for (const entry of await scanner.listDir(joinRepoPath(root, 'bin'))) {
             if (entry.type === 'dir')
                 continue;
             const lower = entry.name.toLowerCase();
@@ -943,32 +914,32 @@ async function detectRepoCliHint(scanner, root, rootEntries) {
                 lower.includes('cli') ||
                 lower === 'dev' ||
                 lower === 'setup') {
-                return { path: joinPath(root, 'bin', entry.name), kind: 'repo-cli' };
+                return { path: joinRepoPath(root, 'bin', entry.name), kind: 'repo-cli' };
             }
         }
     }
     for (const name of MAKEFILE_NAMES) {
         if (fileNames.has(name))
-            return { path: joinPath(root, name), kind: 'makefile' };
+            return { path: joinRepoPath(root, name), kind: 'makefile' };
     }
     for (const name of JUSTFILE_NAMES) {
         if (fileNames.has(name))
-            return { path: joinPath(root, name), kind: 'justfile' };
+            return { path: joinRepoPath(root, name), kind: 'justfile' };
     }
     for (const name of TASKFILE_NAMES) {
         if (fileNames.has(name))
-            return { path: joinPath(root, name), kind: 'taskfile' };
+            return { path: joinRepoPath(root, name), kind: 'taskfile' };
     }
     return undefined;
 }
 /**
  * Build the `docker-compose` recommendation. Beyond the base `composePath` + build-mode detection,
- * this reads the STACK RECIPE a complex compose repo implies (the acme-main pilot): multi-`-f`
+ * this reads the STACK RECIPE a complex compose repo implies (the acme-monolith pilot): multi-`-f`
  * layering, external networks, env-file materialization → `recipe`; profiles + seed dumps →
  * candidate arrays the wizard confirms; a repo-CLI hint → the analyst nudge. When NONE of those are
  * present the output is exactly the simple single-file recommendation (no `recipe`, no extra notes).
  */
-async function buildComposeRecommendation(scanner, root, compose, serviceBasename, kubernetesAlsoExists = false) {
+async function buildComposeRecommendation(scanner, root, compose, serviceBasename, kubernetesAlsoExists = false, conventions) {
     const notes = [
         {
             field: 'provisionType',
@@ -1030,7 +1001,7 @@ async function buildComposeRecommendation(scanner, root, compose, serviceBasenam
             message: `Bind the external network(s) (${compose.externalNetworks.join(', ')}) to a shared stack so it is brought up first, or create them on the host manually.`,
         });
     }
-    const envFiles = await collectEnvFileTemplates(scanner, root, compose.dir);
+    const envFiles = await collectEnvFileTemplates(scanner, root, compose.dir, conventions);
     if (envFiles.length > 0) {
         recipe.envFiles = envFiles;
         notes.push({
@@ -1049,7 +1020,7 @@ async function buildComposeRecommendation(scanner, root, compose, serviceBasenam
             message: `The compose file declares ${profileCandidates.length} profile(s): ${compose.profiles.join(', ')}. All surfaced default-off — enable the optional service groups you need.`,
         });
     }
-    const seedDumpCandidates = await collectSeedDumps(scanner, root);
+    const seedDumpCandidates = await collectSeedDumps(scanner, root, conventions);
     if (seedDumpCandidates.length > 0) {
         const pick = seedDumpCandidates.find((s) => s.recommended);
         notes.push({
@@ -1201,7 +1172,7 @@ async function buildKubernetesRecommendation(scanner, roots, lookupRoot, opts) {
     }
     const secretInjections = [];
     if (scan.secretGenerator) {
-        const envFilePath = joinPath(scan.secretGenerator.baseDir, scan.secretGenerator.envFile);
+        const envFilePath = joinRepoPath(scan.secretGenerator.baseDir, scan.secretGenerator.envFile);
         const exampleDirs = [...new Set([scan.secretGenerator.baseDir, path, lookupRoot])];
         let keys = [];
         for (const dir of exampleDirs) {
@@ -1276,18 +1247,18 @@ async function buildKubernetesRecommendation(scanner, roots, lookupRoot, opts) {
  * candidates for the user to pick, never silently auto-applied beyond the pre-selected one.
  */
 export async function detectKubernetesProvisioning(reader, options = {}) {
-    const root = joinPath(options.directory ?? '');
+    const root = joinRepoPath(options.directory ?? '');
     const repoScanEnabled = root !== '';
     const serviceBasename = root.split('/').pop() ?? '';
-    const scanner = new Scanner(reader, options.gitRef);
+    const scanner = new BudgetedRepoScanner(reader, READ_BUDGET, options.gitRef);
     const roots = await collectKubernetesRoots(scanner, root);
-    const compose = await findCompose(scanner, root);
+    const compose = await findCompose(scanner, root, options.conventions);
     // Honor the selected tab: on docker-compose, recommend the compose file first (noting any
     // co-existing k8s manifests). Falls through to kubernetes when the user is on compose but no
     // compose file exists. With no preference (or any non-compose tab) we keep the historical
     // kubernetes-first order.
     if (options.prefer === 'docker-compose' && compose) {
-        return buildComposeRecommendation(scanner, root, compose, serviceBasename, roots.length > 0);
+        return buildComposeRecommendation(scanner, root, compose, serviceBasename, roots.length > 0, options.conventions);
     }
     // Colocated k8s manifests win (highest confidence). In a monorepo, ALSO surface a root-shared
     // per-service slice as a low-confidence "this might be the deploy target instead" hint — but ONLY
@@ -1347,7 +1318,7 @@ export async function detectKubernetesProvisioning(reader, options = {}) {
         }
     }
     if (compose)
-        return buildComposeRecommendation(scanner, root, compose, serviceBasename);
+        return buildComposeRecommendation(scanner, root, compose, serviceBasename, false, options.conventions);
     // Nothing detected. If that "nothing" is really "the repo couldn't be read" (the scan hit a
     // genuine read fault), raise it rather than falsely reporting an empty repo.
     if (scanner.readFault)
@@ -1375,9 +1346,9 @@ export async function detectKubernetesProvisioning(reader, options = {}) {
  * {@link RepoReadError}; a clean "no compose file here" returns `detected: false`.
  */
 export async function detectSharedStack(reader, options = {}) {
-    const root = joinPath(options.directory ?? '');
-    const scanner = new Scanner(reader, options.gitRef);
-    const compose = await findCompose(scanner, root);
+    const root = joinRepoPath(options.directory ?? '');
+    const scanner = new BudgetedRepoScanner(reader, READ_BUDGET, options.gitRef);
+    const compose = await findCompose(scanner, root, options.conventions);
     if (!compose) {
         // Nothing compose-shaped. Distinguish "couldn't read the repo" from "read it, no compose".
         if (scanner.readFault)
@@ -1437,7 +1408,7 @@ export async function detectSharedStack(reader, options = {}) {
             message: `The compose file declares ${compose.profiles.length} profile(s): ${compose.profiles.join(', ')}. Enable the optional service groups this stack should run.`,
         });
     }
-    const envFiles = await collectEnvFileTemplates(scanner, root, compose.dir);
+    const envFiles = await collectEnvFileTemplates(scanner, root, compose.dir, options.conventions);
     if (envFiles.length > 0) {
         notes.push({
             field: 'envFiles',
@@ -1479,8 +1450,8 @@ export async function detectSharedStack(reader, options = {}) {
  * Never throws / never persists; the SPA confirms the prefilled `manifestPath`.
  */
 export async function detectCustomManifest(reader, options = {}) {
-    const root = joinPath(options.directory ?? '');
-    const scanner = new Scanner(reader, options.gitRef);
+    const root = joinRepoPath(options.directory ?? '');
+    const scanner = new BudgetedRepoScanner(reader, READ_BUDGET, options.gitRef);
     const manifestIdPart = options.manifestId ? { manifestId: options.manifestId } : {};
     const rec = (detected, manifestPath, note) => ({
         detected,
@@ -1509,7 +1480,7 @@ export async function detectCustomManifest(reader, options = {}) {
         });
     }
     // 2a. Exact: the complete relative path (with filename) under the service subtree / repo root.
-    const exact = joinPath(root, defaultPath);
+    const exact = joinRepoPath(root, defaultPath);
     if ((await scanner.getFile(exact)) !== null) {
         return rec(true, exact, {
             field: 'manifestPath',
@@ -1522,7 +1493,7 @@ export async function detectCustomManifest(reader, options = {}) {
         for (const entry of await scanner.listDir(root)) {
             if (entry.type !== 'dir')
                 continue;
-            const nested = joinPath(entry.path, defaultPath);
+            const nested = joinRepoPath(entry.path, defaultPath);
             if ((await scanner.getFile(nested)) !== null) {
                 return rec(true, nested, {
                     field: 'manifestPath',