@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/detectors/index.js

@@ -1,32 +1,10 @@
-/**
- * @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';
 
-/**
- * Common monorepo locations for a frontend `package.json`, root included.
- *
- * Exported so `discoverFrontendPackages()` (src/lib/tasks/test-nodes.js, #87
- * PR B) scans the SAME candidate list this detector already uses — one
- * spelling of "where a frontend package might live", not two that drift.
- */
-export const PACKAGE_LOCATIONS = ['.', 'src/frontend', 'src/web', 'frontend', 'apps/web', 'packages/app'];
-
-/**
- * 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 } }}
- */
+import { PACKAGE_LOCATIONS } from '../../../framework/hooks/shared/frontend-locations.js';
+
+export { PACKAGE_LOCATIONS };
+
 export function detectProject(targetPath, opts = {}) {
   const structure = {
     stack: 'unknown',
@@ -37,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 = [];
@@ -50,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')) {
@@ -73,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');
       }
@@ -89,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'];
 
@@ -110,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) {
@@ -118,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)) {
@@ -161,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',
@@ -181,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;
@@ -190,7 +150,6 @@ export function detectProject(targetPath, opts = {}) {
       structure.integrations.push('azure');
     }
   } catch {
-    // Fail-safe — return defaults
   }
 
   return {
@@ -201,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);
@@ -214,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/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(

package/src/lib/e2e/stack-teardown.js

@@ -1,27 +1,6 @@
-/**
- * Reclaim a feature's verification stack — containers, ports, named volumes
- * and the freshness stamp — from the tree that owns the feature.
- *
- * `morph-spec verify` leaves the stack UP on purpose (cold-starting a
- * container per task is what makes the loop unusable), so something has to be
- * the one place that brings it down when the feature closes. That place is
- * this module, shared by `finish` and `delete --with-worktree`.
- *
- * Three things the old root-side teardown got wrong, each pinned by a test:
- *   1. It ran from the ROOT. A compose that exists only in the worktree was
- *      never found, and a bind mount resolved to the wrong checkout.
- *   2. It passed a bare `COMPOSE_PROJECT_NAME`. Without the port block
- *      (`PORT`, `POSTGRES_PORT`, …) compose resolves a different config than
- *      the one that came up, and `down` misses the containers.
- *   3. It never removed volumes or the stamp. Postgres data and a stamp saying
- *      "source unchanged since build" outlived the feature.
- *
- * Entirely fail-open: no compose, no docker, or a stubborn container are all
- * non-events for the caller — a stack that refuses to come down must never
- * fail a finish that already merged.
- *
- * @module lib/e2e/stack-teardown
- */
+// `verify` leaves the stack up on purpose, so this is the one place that brings it down. Runs from the
+// owning tree with the full port block, or compose resolves a different config and `down` misses it.
+// Fail-open: a stack that refuses to come down must never fail a finish that already merged.
 
 import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
@@ -36,15 +15,6 @@ import {
 } from '../../../framework/hooks/shared/e2e-check.js';
 import { buildComposeEnv } from './compose-env.js';
 
-/**
- * @param {string} feature
- * @param {object} params
- * @param {string} params.root - primary root (absolute)
- * @param {string|null} [params.worktreePath] - the feature's live worktree, if any
- * @param {boolean} [params.volumes=true] - also remove named volumes (`down -v`)
- * @param {Function} [params._exec] - injectable executor (testing)
- * @returns {{ attempted: boolean, cwd: string, status: 'pass'|'fail'|'skip', stampDeleted: boolean, output?: string }}
- */
 export function tearDownFeatureStack(feature, { root, worktreePath = null, volumes = true, _exec = defaultExec } = {}) {
   const cwd = worktreePath && existsSync(worktreePath) ? worktreePath : root;
   const projectName = composeProjectName(feature);
@@ -53,8 +23,7 @@ export function tearDownFeatureStack(feature, { root, worktreePath = null, volum
   try {
     const config = readConfig(cwd) ?? readConfig(root);
 
-    // The owning tree's compose first; the root's copy is the fallback for a
-    // worktree already half torn down (versioned file, so equivalent).
+    // The owning tree's compose first; the root's copy is the fallback for a worktree already half torn down.
     let composeCwd = cwd;
     let composeFile = resolveComposeFile(cwd, config);
     if (!composeFile && cwd !== root) {
@@ -63,8 +32,7 @@ export function tearDownFeatureStack(feature, { root, worktreePath = null, volum
     }
 
     if (!composeFile) {
-      // Nothing to bring down — but a stamp left behind would tell the next
-      // `up` that a stack it cannot see is still fresh.
+      // Nothing to bring down, but a stamp left behind would tell the next `up` a stack it cannot see is fresh.
       return { attempted: false, cwd, status: 'skip', stampDeleted: deleteStamp(gitCommonDir, projectName) };
     }
 
@@ -82,13 +50,11 @@ export function tearDownFeatureStack(feature, { root, worktreePath = null, volum
       ...(result.status === 'fail' && result.output ? { output: result.output } : {}),
     };
   } catch {
-    // Unconditional even when the teardown itself blew up: the stamp must not
-    // outlive the stack it described.
+    // The stamp must not outlive the stack it described, even when the teardown itself blew up.
     return { attempted: false, cwd, status: 'fail', stampDeleted: deleteStamp(gitCommonDir, projectName) };
   }
 }
 
-/** BOM-tolerant config read; null when absent or malformed. */
 function readConfig(dir) {
   try {
     const path = join(dir, '.morph', 'config', 'config.json');