@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/ci/github-ci.js

@@ -21,14 +21,8 @@ function gh(cwd, args, timeout = 15000) {
   return execFileSync(bin, [...prefix, ...args], { cwd, stdio: 'pipe', timeout }).toString();
 }
 
-/**
- * The workflow that can stand in for `verify {feature}`: it must call `morph-spec verify` AND
- * publish its JSON, because only that artifact becomes a stamp. A green run of any other
- * workflow (lint, deploy) proves nothing about the suite.
- *
- * @param {string} root
- * @returns {string|null} workflow file name, as `gh run list --workflow` takes it
- */
+// Must call `morph-spec verify` AND publish its JSON: only that artifact becomes a stamp, and a green
+// lint or deploy run proves nothing about the suite.
 export function findCiWorkflow(root) {
   const dir = join(root, CI_WORKFLOW_DIR);
   if (!existsSync(dir)) return null;
@@ -69,15 +63,7 @@ function ghAuthText(root) {
   return `${res.stdout ?? ''}${res.stderr ?? ''}`;
 }
 
-/**
- * Whether CI can answer for this feature, and why not. Never throws: every "no" is a reason the
- * caller prints before falling back to the local verify.
- *
- * @param {string} root - the feature's tree
- * @param {string} featureName
- * @param {object|null} config - `.morph/config/config.json`
- * @returns {{ ok: true, branch: string, https: boolean, scopes: string|null } | { ok: false, reason: string }}
- */
+/** Never throws: every "no" is a reason the caller prints before falling back to the local verify. */
 export function ciAvailability(root, featureName, config) {
   if (config?.project?.ci === false) return { ok: false, reason: 'project.ci = false no config.json' };
   const url = originUrl(root);
@@ -93,21 +79,14 @@ export function ciAvailability(root, featureName, config) {
   return { ok: true, branch, https: /^https?:/i.test(url), scopes };
 }
 
-/**
- * Creating a workflow file over HTTPS needs the token's `workflow` scope; without it GitHub
- * rejects the whole push. Unknown scopes (fine-grained token, SSH remote) are not a refusal.
- */
+// Creating a workflow file over HTTPS needs the token's `workflow` scope, or GitHub rejects the whole push.
+// Unknown scopes (fine-grained token, SSH remote) are not a refusal.
 export function workflowPushProblem({ https, scopes }) {
   if (!https || scopes === null) return null;
   return /\bworkflow\b/.test(scopes) ? null : 'o token do gh não tem o escopo "workflow" (gh auth refresh -s workflow)';
 }
 
-/**
- * Paths CI would not see: uncommitted or untracked files outside `.morph/`, plus the config,
- * which names the test commands.
- *
- * @returns {string[]|null} null when git did not answer
- */
+/** Uncommitted or untracked files outside `.morph/`, plus the config; null when git did not answer. */
 export function uncommittedCode(root) {
   let out;
   try {
@@ -138,10 +117,8 @@ export function listRuns(root, branch, workflow) {
   }
 }
 
-/**
- * The newest run over the same code as HEAD. `isCurrent` is a tree comparison, not SHA equality:
- * the review agents and the archive commit only `.morph/`, and the workflow does not re-run for them.
- */
+// `isCurrent` compares trees, not SHAs: the review agents and the archive commit only `.morph/`,
+// and the workflow does not re-run for them.
 export function pickRun(runs, isCurrent) {
   return (runs || []).find((run) => !(run.status === 'completed' && NO_VERDICT.has(run.conclusion))
     && run.headSha && isCurrent(run.headSha)) ?? null;
@@ -160,12 +137,7 @@ export function downloadResult(root, runId) {
   }
 }
 
-/**
- * Polls until the run over the current tree completes. Never decides: the caller turns
- * `timeout`/`no-run`/`unknown` into "no CI proof", never into red.
- *
- * @returns {Promise<{ state: 'completed'|'timeout'|'no-run'|'unknown', run?: object }>}
- */
+/** Never decides: the caller turns `timeout`/`no-run`/`unknown` into "no CI proof", never into red. */
 export async function waitForRun(root, { branch, workflow, isCurrent, timeoutMs, appearMs, pollMs = 15000,
   sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, onPending = () => {}, list = listRuns }) {
   const start = now();

package/src/lib/ci/workflow-scaffold.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync } from 'fs';
 import { join, posix, relative, resolve } from 'path';
 import { PACKAGE_LOCATIONS } from '../detectors/index.js';
 import { CI_ARTIFACT, CI_RESULT_FILE } from './github-ci.js';
+import { discoverDotnetSolution } from '../tasks/test-runner.js';
 
 const LOCKFILES = [
   ['package-lock.json', 'npm ci'],
@@ -50,22 +51,24 @@ function dotnetSetup(root, config) {
   ];
 }
 
+// The verify build node runs `dotnet build --no-restore` (right on a warm tree): a fresh checkout restores first,
+// against the same target the build node resolves.
+function dotnetRestore(root, config) {
+  if (!usesDotnet(root, config)) return [];
+  const backend = config?.project?.backendPath;
+  if (typeof backend === 'string') return step('dotnet restore', backend, 'dotnet restore');
+  const { target } = discoverDotnetSolution(root);
+  return step('dotnet restore', '.', target && target !== '.' ? `dotnet restore "${target}"` : 'dotnet restore');
+}
+
 const step = (name, dir, run) => [
   `      - name: ${name}`,
   ...(dir === '.' ? [] : [`        working-directory: ${posix.normalize(dir)}`]),
   `        run: ${run}`,
 ];
 
-/**
- * The workflow `verify {f} --ci` relies on. Same judge as the local run: it calls the project's
- * pinned morph-spec, so the suite is whatever `project.tests` says, not a second definition here.
- * `.morph/` is out of the trigger (bookkeeping commits would cancel the run over the code) except
- * the config, which names the commands.
- *
- * @param {string} root
- * @param {object|null} config
- * @returns {string}
- */
+// Calls the project's pinned morph-spec, so the suite is whatever `project.tests` says. `.morph/` is out of
+// the trigger (bookkeeping commits would cancel the run over the code) except the config.
 export function renderCiWorkflow(root, config) {
   const packages = packageDirs(root, config);
   const lines = [
@@ -102,6 +105,7 @@ export function renderCiWorkflow(root, config) {
     lines.push(...step(`install (${pkg.dir})`, pkg.dir, pkg.install));
     if (pkg.playwright) lines.push(...step(`playwright browsers (${pkg.dir})`, pkg.dir, 'npx playwright install --with-deps chromium'));
   }
+  lines.push(...dotnetRestore(root, config));
   lines.push(
     '      - name: morph-spec verify',
     '        shell: bash',

package/src/lib/detectors/claude-config-detector.js

@@ -1,24 +1,8 @@
-/**
- * @fileoverview Claude Config Detector
- *
- * Scans .claude/ settings and plugins for MCP servers, hooks, skills, and commands.
- * Used by mcp-setup and session-start hooks.
- *
- * @module detectors/claude-config-detector
- */
-
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
-/**
- * Plugin ids (`name@marketplace`) that are switched ON. User settings first, then
- * the project's; a later file overrides an earlier one, and `false` turns one off.
- *
- * @param {string} targetPath - Root path of the project
- * @param {string} [home] - Home directory holding `.claude/settings.json`
- * @returns {string[]}
- */
+// User settings first, then the project's: a later file overrides, and `false` turns a plugin off.
 export function readEnabledPlugins(targetPath, home = homedir()) {
   const merged = new Map();
   const files = [
@@ -32,17 +16,11 @@ export function readEnabledPlugins(targetPath, home = homedir()) {
       const map = JSON.parse(readFileSync(file, 'utf8').replace(/^/, '')).enabledPlugins;
       if (!map || typeof map !== 'object') continue;
       for (const [id, on] of Object.entries(map)) merged.set(id, on === true);
-    } catch { /* invalid JSON */ }
+    } catch {}
   }
   return [...merged].filter(([, on]) => on).map(([id]) => id);
 }
 
-/**
- * Detect Claude Code configuration for a project.
- *
- * @param {string} targetPath - Root path of the project
- * @returns {{ plugins: string[], enabledPlugins: string[], mcpServers: Array<{name: string, config: Object}>, customSkills: string[], customCommands: string[], hooks: string[] }}
- */
 export function detectClaudeConfig(targetPath) {
   const result = {
     plugins: [],
@@ -58,7 +36,6 @@ export function detectClaudeConfig(targetPath) {
   const mcpJsonNames = new Set();
 
   try {
-    // ── MCP Servers from .mcp.json (primary — Claude Code reads this) ───────
     const mcpJsonPath = join(targetPath, '.mcp.json');
     if (existsSync(mcpJsonPath)) {
       try {
@@ -68,10 +45,9 @@ export function detectClaudeConfig(targetPath) {
           result.mcpServers.push({ name, config });
           mcpJsonNames.add(name);
         }
-      } catch { /* invalid JSON */ }
+      } catch {}
     }
 
-    // ── MCP Servers + hooks from settings (legacy + hooks/permissions) ───────
     const settingsPaths = [
       join(targetPath, '.claude', 'settings.json'),
       join(targetPath, '.claude', 'settings.local.json'),
@@ -81,19 +57,18 @@ export function detectClaudeConfig(targetPath) {
       if (existsSync(sp)) {
         try {
           const settings = JSON.parse(readFileSync(sp, 'utf8'));
-          // Legacy MCP entries — skip if already in .mcp.json, but allow later settings files to override earlier ones
+          // Legacy entries: .mcp.json wins; among settings files, the later one wins.
           const mcps = settings.mcpServers || {};
           for (const [name, config] of Object.entries(mcps)) {
-            if (mcpJsonNames.has(name)) continue; // .mcp.json takes priority
+            if (mcpJsonNames.has(name)) continue;
             const idx = result.mcpServers.findIndex(m => m.name === name);
             if (idx >= 0) {
-              result.mcpServers[idx] = { name, config }; // later file wins
+              result.mcpServers[idx] = { name, config };
             } else {
               result.mcpServers.push({ name, config });
             }
           }
 
-          // Collect hooks
           if (settings.hooks) {
             for (const [event, eventHooks] of Object.entries(settings.hooks)) {
               for (const group of (Array.isArray(eventHooks) ? eventHooks : [])) {
@@ -103,60 +78,43 @@ export function detectClaudeConfig(targetPath) {
               }
             }
           }
-        } catch { /* invalid JSON */ }
+        } catch {}
       }
     }
 
-    // ── Plugins from global config ──────────────────────────────────────────
     const pluginsPath = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
     if (existsSync(pluginsPath)) {
       try {
         const pluginsData = JSON.parse(readFileSync(pluginsPath, 'utf8'));
         const plugins = pluginsData.plugins || {};
         result.plugins = Object.keys(plugins);
-      } catch { /* invalid JSON */ }
+      } catch {}
     }
 
-    // ── Custom skills ───────────────────────────────────────────────────────
     const skillsPath = join(targetPath, '.claude', 'skills');
     if (existsSync(skillsPath)) {
       try {
         result.customSkills = readdirSync(skillsPath).filter(f => !f.startsWith('.'));
-      } catch { /* ignore */ }
+      } catch {}
     }
 
-    // ── Custom commands ─────────────────────────────────────────────────────
     const commandsPath = join(targetPath, '.claude', 'commands');
     if (existsSync(commandsPath)) {
       try {
         result.customCommands = readdirSync(commandsPath).filter(f => f.endsWith('.md'));
-      } catch { /* ignore */ }
+      } catch {}
     }
   } catch {
-    // Fail-safe
   }
 
   return result;
 }
 
-/**
- * Cross-reference configured MCPs with the MCP registry's phase matrix.
- *
- * `phaseMatrix` and `currentPhase` default rather than being required: the
- * `init` caller passed only `mcpServers`, so `phaseMatrix[currentPhase]` threw
- * a TypeError that `init`'s outer catch swallowed as
- * "Claude config detection skipped" — taking `saveIntegrations` and
- * `generateSettings` down with it, since both run after this line.
- *
- * @param {Array<{name: string}>} mcpServers - Detected MCP server list
- * @param {Object} [phaseMatrix] - From framework/mcp/registry.json → phaseMatrix
- * @param {string} [currentPhase] - Phase to look up; omit for every phase
- * @returns {{ available: string[], recommended: string[], missing: string[] }}
- */
+// `phaseMatrix`/`currentPhase` default: `init` passes only `mcpServers`, and a throw here was
+// swallowed by its outer catch, skipping the steps after it.
 export function mapMcpsToPhases(mcpServers, phaseMatrix = {}, currentPhase = null) {
   const configuredNames = new Set((mcpServers || []).map(m => m.name.toLowerCase()));
-  // No phase asked for → the union across every phase, deduped. That is what a
-  // caller showing "which of my MCPs this framework uses" wants.
+  // No phase asked for → the union across every phase, deduped.
   const recommended = currentPhase
     ? (phaseMatrix[currentPhase] || [])
     : [...new Set(Object.values(phaseMatrix).flat())];
@@ -168,19 +126,6 @@ export function mapMcpsToPhases(mcpServers, phaseMatrix = {}, currentPhase = nul
   };
 }
 
-/**
- * The MCP-by-phase table `init` prints: every phase that recommends at least
- * one of the MCPs this machine actually has configured.
- *
- * Separate from `mapMcpsToPhases` because the caller wants a per-phase
- * breakdown, not one phase's slice — reaching for the wrong one is what
- * produced `Object.entries()` over `{available, recommended, missing}` and a
- * `.map(m => m.name)` over plain strings.
- *
- * @param {Array<{name: string}>} mcpServers
- * @param {Object} phaseMatrix
- * @returns {Array<{phase: string, available: string[]}>} phases with ≥1 match
- */
 export function mcpAvailabilityByPhase(mcpServers, phaseMatrix = {}) {
   return Object.keys(phaseMatrix)
     .map(phase => ({
@@ -190,12 +135,6 @@ export function mcpAvailabilityByPhase(mcpServers, phaseMatrix = {}) {
     .filter(({ available }) => available.length > 0);
 }
 
-/**
- * Format a human-readable one-liner summary of detected config.
- *
- * @param {{ plugins: string[], mcpServers: Array<{name: string}> }} config
- * @returns {string}
- */
 export function formatConfigSummary(config) {
   const parts = [];
   if (config.mcpServers.length > 0) {

package/src/lib/detectors/index.js

@@ -1,12 +1,3 @@
-/**
- * @fileoverview Project Detector
- *
- * Scans a project directory for stack, architecture, UI library, and integrations.
- * Used by `morph-spec init`, `mcp setup` and the test-node fallback (test-nodes.js).
- *
- * @module detectors/index
- */
-
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 
@@ -14,14 +5,6 @@ import { PACKAGE_LOCATIONS } from '../../../framework/hooks/shared/frontend-loca
 
 export { PACKAGE_LOCATIONS };
 
-/**
- * Detect project structure from filesystem evidence.
- *
- * @param {string} targetPath - Root path of the project
- * @param {Object} [opts] - Options
- * @param {boolean} [opts.generateStandards=false] - Whether to generate inferred markdown
- * @returns {{ structure: { stack: string, architecture: string|null, uiLibrary: string|null, integrations: string[], hasVercel: boolean }, inferred: { markdown: string } }}
- */
 export function detectProject(targetPath, opts = {}) {
   const structure = {
     stack: 'unknown',
@@ -32,8 +15,6 @@ export function detectProject(targetPath, opts = {}) {
   };
 
   try {
-    // ── Package.json analysis ──────────────────────────────────────────────
-    // Collect deps from root and common monorepo subfolders
     const allDeps = {};
     let rootPkg = null;
     let scripts = [];
@@ -45,17 +26,15 @@ export function detectProject(targetPath, opts = {}) {
         if (loc === '.') rootPkg = pkg;
         Object.assign(allDeps, pkg.dependencies, pkg.devDependencies);
         scripts.push(...Object.keys(pkg.scripts || {}));
-        // Track frontend path for config
         if (loc !== '.' && (pkg.dependencies?.next || pkg.dependencies?.react || pkg.dependencies?.vue)) {
           structure.frontendPath = loc;
         }
-      } catch { /* invalid JSON */ }
+      } catch {}
     }
     const depNames = Object.keys(allDeps);
 
     if (depNames.length > 0) {
 
-      // Stack detection from deps
       if (depNames.includes('next')) {
         structure.stack = 'nextjs';
       } else if (depNames.includes('react')) {
@@ -68,12 +47,10 @@ export function detectProject(targetPath, opts = {}) {
         structure.stack = 'nodejs';
       }
 
-      // UI library detection
       if (existsSync(join(targetPath, 'components.json')) || existsSync(join(targetPath, structure.frontendPath || '.', 'components.json')) || depNames.includes('@shadcn/ui')) {
         structure.uiLibrary = 'shadcn';
       }
 
-      // Integrations
       if (depNames.includes('@neondatabase/serverless') || depNames.includes('postgres') || depNames.includes('pg')) {
         structure.integrations.push('neon');
       }
@@ -84,13 +61,11 @@ export function detectProject(targetPath, opts = {}) {
         structure.integrations.push('stripe');
       }
 
-      // Vercel detection
       if (depNames.includes('vercel') || scripts.includes('vercel')) {
         structure.hasVercel = true;
       }
     }
 
-    // ── .csproj detection ──────────────────────────────────────────────────
     let hasDotnet = false;
     const csprojLocations = ['.', 'src', 'src/Api', 'src/Web', 'src/backend'];
 
@@ -105,7 +80,7 @@ export function detectProject(targetPath, opts = {}) {
         if (content.includes('Npgsql')) {
           if (!structure.integrations.includes('neon')) structure.integrations.push('neon');
         }
-      } catch { /* ignore */ }
+      } catch {}
     }
 
     for (const loc of csprojLocations) {
@@ -113,41 +88,34 @@ export function detectProject(targetPath, opts = {}) {
         const dir = join(targetPath, loc);
         if (!existsSync(dir)) continue;
         const entries = readdirSyncSafe(dir);
-        // Direct .csproj files
         for (const e of entries.filter(f => f.endsWith('.csproj'))) {
           checkCsproj(join(dir, e));
         }
-        // One level deeper (e.g., src/backend/MyProject/*.csproj)
         for (const sub of entries) {
           const subDir = join(dir, sub);
           for (const e of readdirSyncSafe(subDir).filter(f => f.endsWith('.csproj'))) {
             checkCsproj(join(subDir, e));
           }
         }
-      } catch { /* ignore */ }
+      } catch {}
     }
 
-    // Determine stack: monorepo (nextjs+dotnet), dotnet, or keep frontend stack
     if (hasDotnet) {
       if (structure.stack === 'nextjs' || structure.stack === 'react' || structure.stack === 'vue') {
-        // Monorepo: frontend + .NET backend
         structure.stack = `${structure.stack}+dotnet`;
       } else if (structure.stack === 'unknown') {
         structure.stack = 'dotnet';
       }
     }
 
-    // ── vercel.json detection ──────────────────────────────────────────────
     if (existsSync(join(targetPath, 'vercel.json'))) {
       structure.hasVercel = true;
     }
 
-    // ── tsconfig.json detection (fallback for stack) ────────────────────────
     if (structure.stack === 'unknown' && existsSync(join(targetPath, 'tsconfig.json'))) {
       structure.stack = 'nodejs';
     }
 
-    // ── Architecture detection ─────────────────────────────────────────────
     try {
       const configPath = join(targetPath, '.morph/config/config.json');
       if (existsSync(configPath)) {
@@ -156,16 +124,14 @@ export function detectProject(targetPath, opts = {}) {
           structure.architecture = config.architecture.style;
         }
       }
-    } catch { /* ignore */ }
+    } catch {}
 
-    // ── Docker detection ───────────────────────────────────────────────────
     if (existsSync(join(targetPath, 'docker-compose.yml')) ||
         existsSync(join(targetPath, 'docker-compose.yaml')) ||
         existsSync(join(targetPath, 'Dockerfile'))) {
       if (!structure.integrations.includes('docker')) structure.integrations.push('docker');
     }
 
-    // ── Azure detection ────────────────────────────────────────────────────
     const azureSignals = [
       '.azure',
       'azure-pipelines.yml',
@@ -176,7 +142,6 @@ export function detectProject(targetPath, opts = {}) {
       const p = join(targetPath, signal);
       if (!existsSync(p)) return false;
       if (signal === 'infra') {
-        // Check for .bicep files inside infra/
         return readdirSyncSafe(p).some(f => f.endsWith('.bicep'));
       }
       return true;
@@ -185,7 +150,6 @@ export function detectProject(targetPath, opts = {}) {
       structure.integrations.push('azure');
     }
   } catch {
-    // Fail-safe — return defaults
   }
 
   return {
@@ -196,11 +160,6 @@ export function detectProject(targetPath, opts = {}) {
   };
 }
 
-/**
- * Safe readdir that returns [] on error.
- * @param {string} dir
- * @returns {string[]}
- */
 function readdirSyncSafe(dir) {
   try {
     return readdirSync(dir);
@@ -209,11 +168,6 @@ function readdirSyncSafe(dir) {
   }
 }
 
-/**
- * Generate a markdown summary from detected structure.
- * @param {Object} structure
- * @returns {string}
- */
 function generateInferredMarkdown(structure) {
   const lines = [`## Detected Stack: ${structure.stack}`];
   if (structure.architecture) lines.push(`Architecture: ${structure.architecture}`);

package/src/lib/e2e/applicability.js

@@ -0,0 +1,37 @@
+import { basename } from 'path';
+import { readPlanChecks } from '../plan/checks.js';
+import { changedPathsAgainst, detectDefaultBranch } from '../git/default-branch.js';
+import { resolveComposeFile } from '../../../framework/hooks/shared/e2e-check.js';
+import { E2E_SPEC_LOCATIONS } from '../../../framework/hooks/shared/frontend-locations.js';
+
+export const E2E_NOT_APPLICABLE = 'not applicable: no `prova: e2e` scenario and the diff touches no UI, e2e spec or container file';
+
+const UI_FILE = /\.(tsx|jsx|vue|svelte|astro|css|scss|sass|less|html)$/i;
+const RUNTIME_FILE = /(^|\/)(dockerfile[^/]*|\.dockerignore|(docker-)?compose[^/]*\.ya?ml|playwright\.config\.[cm]?[jt]s)$/i;
+const E2E_DIR = /(^|\/)e2e\//i;
+const KNOWN_PACKAGE_DIRS = E2E_SPEC_LOCATIONS.filter((dir) => dir !== '.');
+
+function packageDirsOf(config) {
+  const declared = [config?.project?.frontendPath, ...(config?.project?.tests ?? []).filter((n) => n?.runner !== 'dotnet').map((n) => n?.cwd)];
+  const extra = declared.filter((d) => typeof d === 'string').map((d) => d.replace(/\\/g, '/').replace(/^\.\/|\/$/g, '')).filter((d) => d && d !== '.');
+  return [...KNOWN_PACKAGE_DIRS, ...extra];
+}
+
+const touchesRuntime = (file, composeFile, packageDirs) => UI_FILE.test(file)
+  || RUNTIME_FILE.test(file)
+  || E2E_DIR.test(file)
+  || (composeFile && basename(file) === basename(composeFile))
+  || packageDirs.some((dir) => file === dir || file.startsWith(`${dir}/`));
+
+/** Unknown (no git, no base, empty diff) is applicable: the e2e only stands down on evidence. */
+export function e2eApplicability(projectPath, featureName, config) {
+  const { checks } = readPlanChecks(projectPath, featureName);
+  if (checks?.checks?.some((c) => c.proof === 'e2e')) return { applicable: true, reason: 'prova: e2e' };
+  const base = detectDefaultBranch(projectPath);
+  const changed = base ? changedPathsAgainst(base, projectPath).filter((f) => !f.startsWith('.morph/')) : [];
+  if (changed.length === 0) return { applicable: true, reason: 'diff unknown' };
+  const composeFile = resolveComposeFile(projectPath, config);
+  const packageDirs = packageDirsOf(config);
+  const hit = changed.find((f) => touchesRuntime(f, composeFile, packageDirs));
+  return hit ? { applicable: true, reason: hit } : { applicable: false, reason: E2E_NOT_APPLICABLE };
+}

package/src/lib/e2e/compose-env.js

@@ -1,22 +1,5 @@
-/**
- * Compose environment for the e2e stack — the port block a feature owns, plus
- * the credentials its auth setup needs.
- *
- * This lives in ONE place because it has two callers that must never disagree:
- * `morph-spec e2e up` (manual) and the `e2e` node inside `morph-spec verify`
- * (the one that actually runs in the loop). When only the manual path built the
- * port block, the isolation was real in the command nobody runs and absent in
- * the one everybody runs — two worktrees would get distinct container names via
- * COMPOSE_PROJECT_NAME and then collide on host port 3000 anyway, surfacing as
- * "port is already allocated" and pausing a gate over an infrastructure clash
- * rather than a defect.
- *
- * It sits in src/lib rather than framework/hooks/shared because it depends on
- * env-allocator.js: hooks are installed standalone into target projects, where
- * `src/` does not exist, so the dependency may only point this way.
- *
- * @module lib/e2e/compose-env
- */
+// One place for `e2e up` and the `e2e` node of `verify`, which must never disagree on ports. Lives in
+// src/lib, not hooks/shared, because it depends on env-allocator.js and hooks run without `src/`.
 
 import { join } from 'path';
 
@@ -25,43 +8,11 @@ import chalk from 'chalk';
 import { loadEnvFile } from '../../../framework/hooks/shared/e2e-check.js';
 import { allocateEnvBlock, portLayout, resolveFleetConfig, resolvePortAliases } from '../worktree/env-allocator.js';
 
-/**
- * Build the environment a `docker compose` invocation should carry.
- *
- * Port variables come from `portLayout()` in env-allocator.js — the SAME
- * function that renders `.morph/worktree.env` — so a compose file and the
- * worktree manifest describe the same world by construction (`PORT`,
- * `API_PORT`/`ASPNETCORE_URLS`, `POSTGRES_PORT`, `COMPOSE_PROJECT_NAME`).
- *
- * `PLAYWRIGHT_BASE_URL` is derived here rather than left to the spec config —
- * the suite has to be told where the app actually landed, otherwise a feature
- * on port 4020 gets tested against a hardcoded localhost:3000 and fails with
- * ECONNREFUSED that looks exactly like a broken app.
- *
- * The credentials env file loads AFTER the layout but cannot outrank it: a
- * `.env.e2e` copied from a sibling worktree carries THAT worktree's block, and
- * letting it win points this stack at the neighbour's postgres while every
- * other surface still reports the allocated port. The protected keys are the
- * ones actually assigned above — never a second literal list, which is exactly
- * how an offset lands in one writer and not the other. A key that gets ignored
- * is announced on stderr (never stdout: `morph-spec env` writes shell-eval
- * output there), because swapping a silent override for a silent discard just
- * moves the debugging session.
- *
- * Fail-open throughout: with no git dir (or a corrupt registry) the caller gets
- * default ports, which only matters when two stacks run at once. With no layout
- * applied nothing is filtered — there the env file is the only port source.
- *
- * @param {object} params
- * @param {string} params.cwd - project root
- * @param {object|null} [params.config] - .morph/config/config.json contents
- * @param {string} params.featureName
- * @param {string|null} [params.gitCommonDir]
- * @returns {Record<string,string>}
- */
+// Ports come from `portLayout()`, the same function that renders `.morph/worktree.env`. The credentials
+// file loads after the layout but cannot outrank it: a `.env.e2e` copied from a sibling worktree carries
+// that worktree's block. Ignored keys are announced on stderr; stdout carries `morph-spec env` output.
 export function buildComposeEnv({ cwd, config, featureName, gitCommonDir }) {
   const env = {};
-  /** @type {Set<string>|null} - null while no layout has been applied */
   let layoutKeys = null;
 
   if (gitCommonDir) {
@@ -97,18 +48,6 @@ export function buildComposeEnv({ cwd, config, featureName, gitCommonDir }) {
   return env;
 }
 
-/**
- * Tell the caller — `e2e up`, the `e2e` node of `verify`, `stack-teardown` and
- * `morph-spec env` all reach this through `buildComposeEnv` — which keys of the
- * credentials file were dropped and what won instead.
- *
- * stderr, always: `morph-spec env` prints `export K=v` on stdout for a
- * shell to eval, and `verify` prints JSON there.
- *
- * @param {string} envFile
- * @param {string[]} ignored
- * @param {Record<string,string>} env - the layout that won
- */
 function reportIgnoredLayoutKeys(envFile, ignored, env) {
   const shown = ignored.map((key) => `${key}=${env[key]}`).join(', ');
   console.warn(chalk.yellow(