Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

65.1 KB
Raw Blame
import { readFile, readdir, stat } from 'fs/promises';
import { existsSync } from 'fs';
import { join, basename, dirname } from 'path';
import { homedir } from 'os';
import { listProcessesStrict } from './pm2.js';
import { safeJSONParse, tryReadFile, atomicWrite } from '../lib/fileUtils.js';
import { detectAppIcon } from './appIconDetect.js';
import { NON_PM2_TYPES, usesPm2, DESKTOP_TYPES, isDesktopType } from './appProcessTypes.js';
export { NON_PM2_TYPES, usesPm2, DESKTOP_TYPES, isDesktopType };

/**
 * Language markers, checked FIRST: a repo's LANGUAGE beats its packaging, so a
 * Python service that also ships a `Dockerfile` classifies as `python` (the
 * common case) rather than as a Docker stack.
 */
const LANGUAGE_MARKERS = [
  ['python', ['pyproject.toml', 'requirements.txt', 'setup.py', 'Pipfile']],
  ['go', ['go.mod']]
];

/** Compose/Dockerfile markers — only reached when no language marker matched. */
const DOCKER_MARKERS = ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml', 'Dockerfile'];

/**
 * Node entry points meaning "a process runs here". Checked BEFORE the docker
 * and static rules, and mapped to *no* classification rather than to a type: a
 * package-less repo shipping `server.mjs` is a Node app someone containerized
 * (or that also serves a page), and classifying it `docker`/`static` would
 * withdraw standardization from an app that genuinely wants it — the exact
 * false negative this predicate exists to avoid.
 *
 * The basename list is deliberately just `server`, the one name that can only
 * mean a server. `index`, `app`, and `main` are all at least as common as
 * browser scripts loaded by an `index.html`, and treating those as evidence
 * would leave real static sites unclassified (and still offered the Node
 * standardizer) — trading this rule's false negative for the very false
 * positive the issue was filed about.
 */
const SERVER_ENTRY_BASENAMES = ['server'];
const SERVER_ENTRY_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ts'];

const hasNodeServerEntry = (present) =>
  // ECOSYSTEM_CONFIG_FILENAMES (below) is the one list of PM2 config names — a
  // repo carrying one is unambiguously a PM2-managed process app.
  ECOSYSTEM_CONFIG_FILENAMES.some(name => present.has(name)) ||
  SERVER_ENTRY_BASENAMES.some(base => SERVER_ENTRY_EXTENSIONS.some(ext => present.has(`${base}${ext}`)));

/** The non-Node app types `classifyNonNodeType` can emit. */
export const NON_NODE_TYPES = new Set([...LANGUAGE_MARKERS.map(([type]) => type), 'docker', 'static']);

/**
 * Classify a repo's runtime from its top-level filenames, for repos that
 * carried no Node or Apple signal. Returns `null` when nothing matched — the
 * caller keeps `unknown` rather than guessing.
 *
 * @param {string[]} files Top-level entry names (from `readdir`).
 * @returns {'python'|'go'|'docker'|'static'|null}
 */
export function classifyNonNodeType(files) {
  const present = new Set(files || []);
  for (const [type, markers] of LANGUAGE_MARKERS) {
    if (markers.some(marker => present.has(marker))) return type;
  }
  if (hasNodeServerEntry(present)) return null;
  if (DOCKER_MARKERS.some(marker => present.has(marker))) return 'docker';
  if (present.has('index.html')) return 'static';
  return null;
}

/**
 * App types the PM2 standardizer must REFUSE: the Apple types (never PM2 at
 * all) plus the non-Node runtimes above. The standardizer's prompt opens with
 * "You are analyzing a Node.js application" — on a Python/Go/Docker/static repo
 * it doesn't fail, it confidently writes a Node ecosystem config into someone
 * else's project. That is what this predicate exists to stop.
 *
 * It is a DENY list rather than an allowlist of Node types because `type` is a
 * free-form string (`appSchema` in `server/lib/validation.js` defaults it to
 * `express` and accepts any value) PERSISTED on the app record. Installs
 * upgrade on their own schedule, so app records in the wild carry values this
 * file has never heard of — `unknown` from before this classification existed,
 * `node`/`react`/`web` from older detection, whatever a user typed. An
 * allowlist would silently withdraw standardization from every one of them.
 * Only a type we have positively identified as non-Node is refused; anything
 * unrecognized degrades to the previous behavior (offer it, and let the user
 * decide) instead of a button that quietly disappears on upgrade.
 */
export const NON_STANDARDIZABLE_TYPES = new Set([...NON_PM2_TYPES, ...NON_NODE_TYPES]);

/** Whether the PM2 standardizer (which writes a NODE ecosystem config) applies. */
export const isStandardizable = (type) => !NON_STANDARDIZABLE_TYPES.has(type);

/**
 * Detect an optional native Godot launch target alongside the repo's normal
 * web-process configuration.
 *
 * Mixed repos keep their ecosystem/Vite ports as the standard browser Launch,
 * while this target opens the game through a separate autorestart-off process.
 */
export function detectGodotNativeLaunch(dirPath) {
  const launcherPath = join(dirPath, 'scripts', 'game');
  const hasLauncher = existsSync(launcherPath);
  let projectPath = null;
  if (existsSync(join(dirPath, 'project.godot'))) {
    projectPath = 'project.godot';
  } else if (hasLauncher && existsSync(join(dirPath, 'game', 'project.godot'))) {
    projectPath = join('game', 'project.godot');
  }
  if (!projectPath) return null;

  const projectDir = dirname(projectPath);
  const slug = basename(dirPath)
    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-|-$/g, '');

  return {
    label: 'Godot',
    command: hasLauncher
      ? './scripts/game run'
      : `godot --path ${projectDir === '.' ? '.' : projectDir}`,
    processName: `${slug || 'godot'}-game`
  };
}

/**
 * Ecosystem config filenames in the order they're resolved. The READER
 * (parseEcosystemFromPath) and the WRITER (writeEcosystemPorts) must agree on
 * this order: if a repo has both, the writer has to rewrite the same file the
 * reader derives ports from, or a port edit lands in a file detection ignores
 * and silently reverts on the next refresh.
 */
const ECOSYSTEM_CONFIG_FILENAMES = ['ecosystem.config.js', 'ecosystem.config.cjs'];

/**
 * Count the run of consecutive backslashes immediately before `idx`.
 * An odd count means the character at `idx` is escaped; even (including 0)
 * means it isn't — `\"` is an escaped quote, but `\\"` is an escaped backslash
 * followed by a real quote.
 */
function isEscaped(content, idx) {
  let count = 0;
  for (let i = idx - 1; i >= 0 && content[i] === '\\'; i--) count++;
  return count % 2 === 1;
}

/**
 * Find the index of the `}` that matches the `{` at `openBraceIdx`, ignoring
 * braces inside strings (single/double/backtick) and JS comments. Returns -1
 * if no match. Backticks are treated as opaque so `${...}` interpolations
 * don't perturb the depth count of the surrounding object.
 */
function findMatchingBrace(content, openBraceIdx) {
  let depth = 0;
  let inString = false;
  let stringChar = null;
  let inLineComment = false;
  let inBlockComment = false;

  for (let i = openBraceIdx; i < content.length; i++) {
    const char = content[i];
    const nextChar = i < content.length - 1 ? content[i + 1] : '';

    if (!inString && !inBlockComment && char === '/' && nextChar === '/') { inLineComment = true; continue; }
    if (inLineComment && char === '\n') { inLineComment = false; continue; }
    if (!inString && !inLineComment && char === '/' && nextChar === '*') { inBlockComment = true; continue; }
    if (inBlockComment && char === '*' && nextChar === '/') { inBlockComment = false; i++; continue; }
    if (inLineComment || inBlockComment) continue;

    if ((char === '"' || char === "'" || char === '`') && !isEscaped(content, i)) {
      if (!inString) { inString = true; stringChar = char; }
      else if (char === stringChar) { inString = false; stringChar = null; }
    }

    if (!inString) {
      if (char === '{') depth++;
      else if (char === '}') {
        depth--;
        if (depth === 0) return i;
      }
    }
  }
  return -1;
}

/**
 * Parse ecosystem.config.js/cjs to extract all processes with their ports
 * Uses regex parsing since we can't safely execute arbitrary JS
 * @returns {{ processes: Array, pm2Home: string|null }}
 */
export function parseEcosystemConfig(content) {
  const processes = [];
  let pm2Home = null;

  // Extract PM2_HOME constant if defined (e.g., const PM2_HOME = `${require("os").homedir()}/.pm2-grace`)
  // First try template literals (backticks) which can contain nested quotes
  const templateMatch = content.match(/(?:const|let|var)\s+PM2_HOME\s*=\s*`([^`]+)`/);
  if (templateMatch) {
    let homePath = templateMatch[1];
    // Replace common template expressions
    homePath = homePath.replace(/\$\{require\(['"]os['"]\)\.homedir\(\)\}/g, homedir());
    homePath = homePath.replace(/\$\{require\(['"]os['"]\)\.userInfo\(\)\.username\}/g, process.env.USER || 'user');
    homePath = homePath.replace(/\$\{process\.env\.HOME\}/g, homedir());
    pm2Home = homePath;
  } else {
    // Try regular string literals
    const stringMatch = content.match(/(?:const|let|var)\s+PM2_HOME\s*=\s*['"]([^'"]+)['"]/);
    if (stringMatch) {
      pm2Home = stringMatch[1];
    } else {
      // Check for PM2_HOME in env blocks
      const envPm2HomeMatch = content.match(/PM2_HOME\s*:\s*PM2_HOME/);
      if (envPm2HomeMatch) {
        // PM2_HOME is used but defined as a variable - try template literal first
        const varTemplateMatch = content.match(/PM2_HOME\s*=\s*`([^`]+)`/);
        if (varTemplateMatch) {
          let homePath = varTemplateMatch[1];
          homePath = homePath.replace(/\$\{require\(['"]os['"]\)\.homedir\(\)\}/g, homedir());
          homePath = homePath.replace(/\$\{require\(['"]os['"]\)\.userInfo\(\)\.username\}/g, process.env.USER || 'user');
          pm2Home = homePath;
        }
      }
    }
  }

  // Extract top-level port constants (e.g., const CDP_PORT = 5549)
  const portConstants = {};
  const constMatches = content.matchAll(/(?:const|let|var)\s+(\w*PORT\w*)\s*=\s*(\d+)/g);
  for (const match of constMatches) {
    portConstants[match[1]] = parseInt(match[2], 10);
  }

  // Extract PORTS object - handles both flat and nested structures
  // Flat: const PORTS = { WEB: 5550, API: 5551 }
  // Nested: const PORTS = { server: { api: 5555 }, client: { ui: 5554 } }
  const portsObjStart = content.match(/(?:const|let|var)\s+PORTS\s*=\s*\{/);
  if (portsObjStart) {
    const startIdx = portsObjStart.index + portsObjStart[0].length - 1;
    let braceCount = 0;
    let endIdx = startIdx;
    for (let i = startIdx; i < content.length; i++) {
      if (content[i] === '{') braceCount++;
      if (content[i] === '}') {
        braceCount--;
        if (braceCount === 0) {
          endIdx = i;
          break;
        }
      }
    }
    const portsBlock = content.substring(startIdx, endIdx + 1);

    // Parse flat entries: KEY: 5550
    const flatEntries = portsBlock.matchAll(/(\w+)\s*:\s*(\d+)/g);
    for (const entry of flatEntries) {
      portConstants[`PORTS.${entry[1]}`] = parseInt(entry[2], 10);
    }

    // Parse nested entries: key: { subkey: 5550 }
    const nestedMatches = portsBlock.matchAll(/(\w+)\s*:\s*\{([^}]+)\}/g);
    for (const nestedMatch of nestedMatches) {
      const parentKey = nestedMatch[1];
      const nestedContent = nestedMatch[2];
      const nestedPorts = {};
      const subEntries = nestedContent.matchAll(/(\w+)\s*:\s*(\d+)/g);
      for (const subEntry of subEntries) {
        const port = parseInt(subEntry[2], 10);
        portConstants[`PORTS.${parentKey}.${subEntry[1]}`] = port;
        nestedPorts[subEntry[1]] = port;
      }
      // Also store the whole nested object for `ports: PORTS.server` references
      portConstants[`PORTS.${parentKey}`] = nestedPorts;
    }
  }

  // Match each app block: { name: '...', ... }
  // This regex captures app objects including nested braces
  const appBlockRegex = /\{\s*name\s*:\s*['"]([^'"]+)['"]/g;
  let match;
  let _lastIndex = 0;

  while ((match = appBlockRegex.exec(content)) !== null) {
    const processName = match[1];
    const startPos = match.index;

    // Find the end of this app block by counting braces
    let braceCount = 0;
    let endPos = startPos;
    let inString = false;
    let stringChar = null;
    let inLineComment = false;
    let inBlockComment = false;

    for (let i = startPos; i < content.length; i++) {
      const char = content[i];
      const nextChar = i < content.length - 1 ? content[i + 1] : '';

      // Handle line comments (// ...)
      if (!inString && !inBlockComment && char === '/' && nextChar === '/') {
        inLineComment = true;
        continue;
      }
      if (inLineComment && char === '\n') {
        inLineComment = false;
        continue;
      }

      // Handle block comments (/* ... */)
      if (!inString && !inLineComment && char === '/' && nextChar === '*') {
        inBlockComment = true;
        continue;
      }
      if (inBlockComment && char === '*' && nextChar === '/') {
        inBlockComment = false;
        i++; // Skip the closing /
        continue;
      }

      // Skip if in any comment
      if (inLineComment || inBlockComment) continue;

      // Backticks count as string delimiters so `${...}` braces don't perturb
      // the count. Use isEscaped() so an even-length backslash run before a
      // quote (e.g. `\\"`) correctly reads as not-escaped.
      if ((char === '"' || char === "'" || char === '`') && !isEscaped(content, i)) {
        if (!inString) {
          inString = true;
          stringChar = char;
        } else if (char === stringChar) {
          inString = false;
          stringChar = null;
        }
      }

      if (!inString) {
        if (char === '{') braceCount++;
        if (char === '}') {
          braceCount--;
          if (braceCount === 0) {
            endPos = i;
            break;
          }
        }
      }
    }

    const appBlock = content.substring(startPos, endPos + 1);

    // Extract ports - first try the PortOS standard 'ports' object
    let ports = {};

    // Look for ports: { label: port, ... } object with literal values
    const portsObjMatch = appBlock.match(/\bports\s*:\s*\{([^}]+)\}/);
    if (portsObjMatch) {
      const portsContent = portsObjMatch[1];
      const portEntries = portsContent.matchAll(/(\w+)\s*:\s*(\d+)/g);
      for (const entry of portEntries) {
        ports[entry[1]] = parseInt(entry[2], 10);
      }
    }

    // Look for ports: VARIABLE reference (e.g., ports: PORTS.server)
    if (Object.keys(ports).length === 0) {
      const portsVarMatch = appBlock.match(/\bports\s*:\s*([\w.]+)/);
      if (portsVarMatch) {
        const varRef = portsVarMatch[1];
        const resolved = portConstants[varRef];
        if (resolved && typeof resolved === 'object') {
          ports = { ...resolved };
        }
      }
    }

    // Fall back to legacy parsing if no ports object found
    if (Object.keys(ports).length === 0) {
      // Helper to resolve port value from literal, variable reference, or expression
      // Handles: 4420, PORTS.API, process.env.PORT || 4420, Number(...) || 4420
      const resolvePortValue = (value) => {
        const trimmed = value.trim();
        if (/^\d+$/.test(trimmed)) return parseInt(trimmed, 10);
        // Expression with || fallback: "process.env.PORT || 4420"
        const fallbackMatch = trimmed.match(/\|\|\s*['"]?(\d+)['"]?\s*$/);
        if (fallbackMatch) return parseInt(fallbackMatch[1], 10);
        // PORTS.XXX or constant reference
        if (portConstants[trimmed]) return portConstants[trimmed];
        return null;
      };

      // Collect every `<NAME>_PORT` env-var first, label after — so CDP_PORT
      // can influence the smart label chosen for PORT regardless of source order.
      // The `_PORT` suffix requirement avoids matching identifiers like REPORT.
      // Brace-counting (not `[^}]*`) so env values with nested objects/ternaries
      // don't truncate the scan at the first inner `}`.
      // Iterate env blocks in PM2 precedence order (env < env_development <
      // env_production) and let later writes overwrite — so when a port is
      // redefined per-environment, the production value is the one we surface.
      const envBlockPrecedence = { env: 0, env_development: 1, env_production: 2 };
      const envHeaderRegex = /\b(env|env_development|env_production)\s*:\s*\{/g;
      const envBlocks = [];
      let envHeaderMatch;
      while ((envHeaderMatch = envHeaderRegex.exec(appBlock)) !== null) {
        const envName = envHeaderMatch[1];
        const openIdx = envHeaderMatch.index + envHeaderMatch[0].length - 1;
        const closeIdx = findMatchingBrace(appBlock, openIdx);
        if (closeIdx < 0) continue;
        envBlocks.push({
          envName,
          index: envHeaderMatch.index,
          envContent: appBlock.substring(openIdx + 1, closeIdx),
        });
      }
      envBlocks.sort((a, b) => {
        const pd = envBlockPrecedence[a.envName] - envBlockPrecedence[b.envName];
        return pd !== 0 ? pd : a.index - b.index;
      });

      const envPorts = {};
      // `['"]?` lets quoted keys like `'PORT': 3000` or `"COINBASE_IPC_PORT": 5565`
      // match — common in JSON-style ecosystem configs. `\b` still anchors the key.
      const portKeyRegex = /['"]?\b(PORT|[A-Z][A-Z0-9_]*_PORT)\b['"]?\s*:\s*([^,}\n]+)/g;
      for (const { envContent } of envBlocks) {
        portKeyRegex.lastIndex = 0;
        let m;
        while ((m = portKeyRegex.exec(envContent)) !== null) {
          const key = m[1];
          const resolved = resolvePortValue(m[2]);
          if (resolved) envPorts[key] = resolved; // last write wins
        }
      }

      const isUiProcess = /[-_](ui|client)$/i.test(processName);
      const isBrowserProcess = /[-_]browser$/i.test(processName);

      if (envPorts.CDP_PORT !== undefined) ports.cdp = envPorts.CDP_PORT;
      if (envPorts.PORT !== undefined) {
        if (isUiProcess) {
          ports.ui = envPorts.PORT;
        } else if (isBrowserProcess && ports.cdp !== undefined) {
          // Browser processes pair CDP_PORT (DevTools) with PORT (health endpoint).
          ports.health = envPorts.PORT;
        } else {
          ports.api = envPorts.PORT;
        }
      }
      if (envPorts.VITE_PORT !== undefined) ports.ui = envPorts.VITE_PORT;

      // FOO_BAR_PORT → fooBar, capturing app-specific labels (coinbaseIpc, etc.).
      for (const [key, value] of Object.entries(envPorts)) {
        if (key === 'PORT' || key === 'VITE_PORT' || key === 'CDP_PORT') continue;
        const stem = key.replace(/_?PORT$/, '');
        if (!stem) continue;
        const label = stem.toLowerCase().replace(/_(\w)/g, (_, c) => c.toUpperCase());
        if (ports[label] === undefined) ports[label] = value;
      }

      // Also check for --port in args
      if (Object.keys(ports).length === 0) {
        const argsPortMatch = appBlock.match(/args\s*:\s*['"][^'"]*--port\s+(\d+)/);
        if (argsPortMatch) {
          ports.ui = parseInt(argsPortMatch[1], 10);
        }
      }

      // Check for port: XXXX directly (some configs use this)
      if (Object.keys(ports).length === 0) {
        const directPortMatch = appBlock.match(/\bport\s*:\s*(\d+)/);
        if (directPortMatch) {
          ports.api = parseInt(directPortMatch[1], 10);
        }
      }
    }

    // Primary port is the first one found (for backwards compatibility)
    const portValues = Object.values(ports);
    const port = portValues.length > 0 ? portValues[0] : null;

    // Extract cwd for processes that might have external config files
    let cwd = null;
    const cwdMatch = appBlock.match(/cwd\s*:\s*['"]([^'"]+)['"]/);
    if (cwdMatch) {
      cwd = cwdMatch[1];
    }

    // Check if this process uses vite (need to check vite.config in cwd)
    // Match explicit "vite" command OR VITE_PORT in env config
    const usesVite = /\bvite\b/i.test(appBlock) || /VITE_PORT/i.test(appBlock);

    processes.push({ name: processName, port, ports, cwd, usesVite });
    _lastIndex = endPos;
  }

  // Post-process: when an app has both an API process and Vite dev processes,
  // relabel Vite ports from 'ui' to 'devUi' since the prod UI is served by the API.
  const hasApiProcess = processes.some(p => p.ports?.api);
  if (hasApiProcess) {
    for (const proc of processes) {
      if (proc.usesVite && proc.ports?.ui && !proc.ports?.devUi) {
        proc.ports.devUi = proc.ports.ui;
        delete proc.ports.ui;
        // Update primary port reference
        const portValues = Object.values(proc.ports);
        proc.port = portValues.length > 0 ? portValues[0] : null;
      }
    }
  }

  return { processes, pm2Home };
}

/**
 * Extract port from vite.config.js/ts content
 */
function extractVitePort(content) {
  const portMatch = content.match(/port\s*:\s*(\d+)/);
  return portMatch ? parseInt(portMatch[1], 10) : null;
}

/** vite config filenames probed inside a PM2 process's `cwd`, in probe order. */
const VITE_CONFIG_FILENAMES = ['vite.config.ts', 'vite.config.js'];

/**
 * Resolve the dev-server port for a single parsed PM2 process by reading the
 * vite config in its `cwd`, relative to the app root `dirPath`.
 *
 * Only applies to a process that runs Vite and carries no port of its own — any
 * other process resolves to `null` so callers can assign unconditionally. The
 * first config file that yields a port wins; an unreadable file is treated as
 * empty (no port) and the next candidate is probed.
 *
 * @param {string} dirPath - app root the process's `cwd` is relative to
 * @param {{ usesVite?: boolean, port?: number|null, cwd?: string }} proc
 * @returns {Promise<number|null>} the resolved port, or null when none applies
 */
export async function resolveViteConfigPortForProcess(dirPath, proc) {
  if (!proc?.usesVite || proc.port || !proc.cwd) return null;
  const cwdPath = join(dirPath, proc.cwd);
  for (const viteConfig of VITE_CONFIG_FILENAMES) {
    const viteConfigPath = join(cwdPath, viteConfig);
    if (!existsSync(viteConfigPath)) continue;
    const viteContent = await readFile(viteConfigPath, 'utf-8').catch(() => '');
    const port = extractVitePort(viteContent);
    if (port) return port;
  }
  return null;
}

/**
 * Parse ecosystem config from a directory path (non-streaming, for refresh)
 * Also checks vite.config files in subdirectories for processes that use Vite
 * @returns {{ processes: Array, pm2Home: string|null }}
 */
export async function parseEcosystemFromPath(dirPath) {
  for (const ecosystemFile of ECOSYSTEM_CONFIG_FILENAMES) {
    const ecosystemPath = join(dirPath, ecosystemFile);
    if (existsSync(ecosystemPath)) {
      const content = await readFile(ecosystemPath, 'utf-8');
      const { processes, pm2Home } = parseEcosystemConfig(content);

      // For processes that use vite and don't have a port, check their cwd for vite.config
      for (const proc of processes) {
        const vitePort = await resolveViteConfigPortForProcess(dirPath, proc);
        if (vitePort) proc.port = vitePort;
        // Clean up internal properties before returning
        delete proc.cwd;
        delete proc.usesVite;
      }

      return { processes, pm2Home };
    }
  }
  return { processes: [], pm2Home: null };
}

/**
 * Brace-matched `{ start, end }` regions whose numeric values are rewritten
 * by VALUE regardless of key name: every `const PORTS = {...}` block AND every
 * per-app `ports: { api: N, ui: N }` object. parseEcosystemConfig reads the
 * per-app `ports:` object FIRST when deriving uiPort/apiPort/devUiPort, so a
 * rewrite that skipped it would let the edit silently revert on the next
 * config refresh — the exact bug the write-back exists to prevent.
 *
 * Commented-out matches are skipped: rewriting a port inside a commented
 * `const PORTS = {...}` would make writeEcosystemPorts report success while the
 * executable config is untouched (the per-region slice starts at the `{`, so
 * the region's own comment scan can no longer see the leading `//`/`/*`).
 */
function findValuePortRegions(content) {
  const comments = commentRanges(content);
  const inComment = (pos) => comments.some(([s, e]) => pos >= s && pos < e);
  const regions = [];
  // `const PORTS = {` (uppercase, any declarator) OR a lowercase `ports: {`
  // object value — the latter is case-sensitive so it won't match `const PORTS`
  // or `reports:`.
  const re = /(?:(?:const|let|var)\s+PORTS\s*=\s*|\bports\s*:\s*)\{/g;
  let m;
  while ((m = re.exec(content)) !== null) {
    if (inComment(m.index)) continue;
    const open = m.index + m[0].length - 1;
    const end = findMatchingBrace(content, open);
    if (end >= 0) regions.push({ start: open, end });
  }
  return regions;
}

/**
 * Byte ranges `[start, end)` covered by line comments and block comments,
 * skipping comment markers that appear inside string/template literals. Used to
 * keep the port rewrite from matching (and falsely "succeeding" on) a port that
 * only appears in a comment.
 */
function commentRanges(content) {
  const ranges = [];
  let i = 0;
  const n = content.length;
  let inString = false;
  let stringChar = null;
  while (i < n) {
    const c = content[i];
    const nx = i + 1 < n ? content[i + 1] : '';
    if (inString) {
      if (c === '\\') { i += 2; continue; }
      if (c === stringChar) inString = false;
      i++;
      continue;
    }
    if (c === '"' || c === "'" || c === '`') { inString = true; stringChar = c; i++; continue; }
    if (c === '/' && nx === '/') {
      const start = i; i += 2;
      while (i < n && content[i] !== '\n') i++;
      ranges.push([start, i]);
      continue;
    }
    if (c === '/' && nx === '*') {
      const start = i; i += 2;
      while (i < n && !(content[i] === '*' && content[i + 1] === '/')) i++;
      i += 2;
      ranges.push([start, Math.min(i, n)]);
      continue;
    }
    i++;
  }
  return ranges;
}

/**
 * Replace every match of `re` in `str` with `${prefix}${replacement}`, EXCEPT
 * matches whose port number falls inside a comment. `re` must have its port
 * number as the final capture run so we can locate where the digits begin: a
 * value living only in a comment (`// PORT: 5173`) must NOT count as a rewrite,
 * or the writer would report changed:true while the executable config is
 * untouched, recreating the apps.json-vs-PM2 mismatch the write-back prevents.
 */
function replaceOutsideComments(str, re, replacement) {
  const ranges = commentRanges(str);
  return str.replace(re, (full, prefix, offset) => {
    const numStart = offset + prefix.length;
    return ranges.some(([s, e]) => numStart >= s && numStart < e) ? full : `${prefix}${replacement}`;
  });
}

/**
 * Find the `{ start, end }` brace-matched region of the app block whose
 * `name:` equals `processName`. Mirrors the block-scan parseEcosystemConfig
 * uses, so a per-process rewrite targets exactly the block the parser derived
 * that process's ports from. Returns the first match (parser semantics) or null.
 */
function findAppBlock(content, processName) {
  const re = /\{\s*name\s*:\s*['"]([^'"]+)['"]/g;
  let m;
  while ((m = re.exec(content)) !== null) {
    if (m[1] !== processName) continue;
    const end = findMatchingBrace(content, m.index);
    if (end >= 0) return { start: m.index, end };
  }
  return null;
}

/**
 * Within a single app block, rewrite the port literal that belongs to `label`
 * (`api`/`ui`/`devUi`) from `oldP` → `newP`, leaving sibling labels alone.
 *
 * The key insight that makes per-label targeting safe inside one block: `PORT`
 * maps to exactly ONE label per process (api OR ui, decided by process name) —
 * the two never collide in the same block. So when two labels share a literal
 * value, they either live in different blocks (block scoping splits them) or in
 * an explicit `ports: { api: N, ui: N }` map (the label KEY splits them). The
 * value-keyed rewriter can't disambiguate either; this one can.
 *
 * Sources rewritten per label mirror parseEcosystemConfig's derivation AND the
 * PM2 runtime env (so the config the parser reads and the env PM2 launches with
 * both move together):
 *   - api  → `ports: { api: N }`, plus env `PORT`/`PORT: … || N`/`port:` ONLY
 *            when the block has no `ports:` REFERENCE (`ports: PORTS.server`) —
 *            for a reference the parser reads the external const, not env, so
 *            rewriting env would falsely report success while the real source
 *            (and displayed port) reverts on refresh.
 *   - ui   → exact `ui:` key, env `VITE_PORT`, `--port N`, and bare env `PORT`
 *            only when there's no explicit ports source (inline object OR
 *            reference) — a UI-named process whose bare `PORT` IS the UI port.
 *   - devUi → exact `devUi:` key (same env/args/bare-PORT sources as ui), PLUS
 *            a Vite process's `ui:` literal when the block has no explicit
 *            `devUi:` key (parseEcosystemConfig relabels ui→devUi when an api
 *            sibling exists, so the on-disk source for that devUi IS `ui:`).
 *
 * Matching the EXACT label key (not a combined `ui|devUi`) means a block that
 * carries both `ui:` and `devUi:` with the same value only rewrites the one the
 * user edited — the sibling keeps its literal.
 *
 * @returns {{ block: string, changed: boolean }}
 */
function rewriteLabelInBlock(block, label, oldP, newP, processName = '') {
  // Swap the matched digits to a sentinel first, then resolve the sentinel to
  // the new value — so a label whose old/new values overlap another source in
  // the same block can't chain. Each prefix capture group is preserved, so only
  // the number changes (no whitespace artifact).
  const ph = 'PORT_TGT_PLACEHOLDER';
  const NUM = `${oldP}\\b`;
  // An explicit ports source is what parseEcosystemConfig derives from. An
  // inline `ports: { ... }` object is rewritable in-block; a `ports: PORTS.x`
  // REFERENCE points at an external const this block can't reach, so the
  // same-valued env literal must NOT be used as a fallback for it (false
  // success + silent runtime-env change). Both forms mean env `PORT` is
  // metadata, not the parser's value.
  const hasInlinePortsObj = /\bports\s*:\s*\{/.test(block);
  const hasPortsReference = /\bports\s*:\s*[A-Za-z_$]/.test(block);
  const hasExplicitPortsSource = hasInlinePortsObj || hasPortsReference;
  // Note: a `ports: SOME_REF` whose constant parseEcosystemConfig can't resolve
  // makes the parser fall back to env/args — but this block-level rewriter has
  // no constant table, so it can't tell a resolved reference from an unresolved
  // one and conservatively treats ALL references as explicit sources (suppresses
  // the env fallback). The cost is a safe 422 on that uncommon malformed-config
  // shape (no corruption), not a wrong write; resolving it would mean threading
  // the parser's resolved-port map down into this pure function.
  // `PORT`/`'PORT'`/`` `PORT` `` followed by `:` and optional whitespace.
  const PORT_KEY = "['\"`]?\\bPORT\\b['\"`]?\\s*:\\s*";
  // Which label does a bare env `PORT` map to? Mirror parseEcosystemConfig:
  // a `-ui`/`-client`-suffixed process routes bare PORT → ui; otherwise → api.
  // (A browser process routes PORT → health, which is none of api/ui/devUi.)
  // PM2 launches with this env var, so the bare PORT must move with its label's
  // port even when an inline ports object is also present — otherwise the
  // process restarts on the old port while the config/registry show the new.
  const isUiProcess = /[-_](ui|client)$/i.test(processName);
  const isBrowserProcess = /[-_]browser$/i.test(processName);
  const barePortLabel = isBrowserProcess ? 'health' : (isUiProcess ? 'ui' : 'api');
  // Label-specific runtime env var, mirroring parseEcosystemConfig's
  // `<STEM>_PORT` → camelCased-stem labeling (API_PORT→api, UI_PORT→ui,
  // DEV_UI_PORT→devUi). PM2 launches the process WITH this env var, so a shared
  // inline `ports` edit that left it on the old value would revert at runtime.
  const LABEL_ENV_KEY = { api: 'API_PORT', ui: 'UI_PORT', devUi: 'DEV_UI_PORT' }[label];

  // Patterns are split by SCOPE:
  //   - portsObjPats run ONLY inside the inline `ports: { ... }` slice. The
  //     `api:`/`ui:`/`devUi:` keys are valid only there (the only place
  //     parseEcosystemConfig reads them); applied over the whole block they'd
  //     also hit a same-named field elsewhere (e.g. `metadata: { api: N }`) and
  //     mutate config the parser never used as the port source.
  //   - blockPats run over the whole block (env keys, args, bare PORT).
  const portsObjPats = [];
  const blockPats = [];
  // Bare env `PORT` should be rewritten whenever it maps to THIS label (per the
  // process name), regardless of whether an inline ports object also exists —
  // PM2 launches with it, so it must track the label's port. NOT for a ports
  // REFERENCE block: there the parser reads the external const and ignores env,
  // so rewriting the bare PORT would be a false-success runtime-only change.
  // A UI process's bare PORT serves BOTH `ui` and `devUi`: when an API sibling
  // exists parseEcosystemConfig relabels that parsed ui port to devUi, so a
  // devUi edit on a UI-named process targets the same bare PORT.
  const barePortIsThisLabel = barePortLabel === label || (barePortLabel === 'ui' && label === 'devUi');
  const rewriteBarePort = barePortIsThisLabel && !hasPortsReference;

  if (label === 'api') {
    if (hasInlinePortsObj) portsObjPats.push(`(\\bapi\\s*:\\s*)${NUM}`);  // ports: { api: N }
    if (rewriteBarePort) {
      // The env `PORT` (and its `|| N` fallback) is the runtime API port here.
      blockPats.push(`(${PORT_KEY}[^,}\\n]*?\\|\\|\\s*['"]?)${NUM}`);     // PORT: … || N (fallback)
      blockPats.push(`(${PORT_KEY})${NUM}`);                             // env PORT: N
    }
    if (!hasPortsReference) {
      // Label-specific runtime env var (API_PORT) — PM2 launches with it.
      blockPats.push(`(['"\`]?\\b${LABEL_ENV_KEY}\\b['"\`]?\\s*:\\s*)${NUM}`); // env API_PORT: N
    }
    // A bare lowercase `port:` is parseEcosystemConfig's LAST-RESORT derivation
    // (`directPortMatch`), consulted only when there's no ports object/env. So
    // rewrite it ONLY when there's no explicit ports source — otherwise it'd
    // hit an unrelated same-valued field (e.g. `metadata: { port: 6000 }`) the
    // parser never read as the API port.
    if (!hasExplicitPortsSource) blockPats.push(`(\\bport\\s*:\\s*)${NUM}`); // port: N
  } else {
    const hasDevUiKey = /\bdevUi\s*:\s*\d/.test(block);
    if (hasInlinePortsObj) {
      portsObjPats.push(label === 'devUi' ? `(\\bdevUi\\s*:\\s*)${NUM}` : `(\\bui\\s*:\\s*)${NUM}`); // exact key
      if (label === 'devUi' && !hasDevUiKey) portsObjPats.push(`(\\bui\\s*:\\s*)${NUM}`); // relabeled-from-ui source
    }
    if (!hasPortsReference) {
      // VITE_PORT/--port mirror the runtime UI/dev port: rewrite them alongside
      // an inline ports key (desirable — config + runtime move together) or as
      // the sole source when there's no ports object. But NOT for a ports
      // REFERENCE whose external const the parser actually reads — rewriting
      // only the env/args value there is false success (the unchanged const
      // re-derives the old port on the next refresh).
      blockPats.push(`(['"\`]?\\bVITE_PORT\\b['"\`]?\\s*:\\s*)${NUM}`); // env VITE_PORT: N
      blockPats.push(`(--port\\s+)${NUM}`);                            // args --port N
      // Label-specific runtime env var (UI_PORT / DEV_UI_PORT) — PM2 launches with it.
      blockPats.push(`(['"\`]?\\b${LABEL_ENV_KEY}\\b['"\`]?\\s*:\\s*)${NUM}`); // env UI_PORT: N
    }
    // Bare env `PORT` is the UI port when this is a UI-named process — rewrite it
    // even alongside an inline ports object (it's the runtime port PM2 uses).
    if (rewriteBarePort) blockPats.push(`(${PORT_KEY})${NUM}`); // bare PORT of a UI-named process
  }

  let out = block;
  // Label-key patterns: rewrite only within the `ports: { ... }` object slice.
  if (portsObjPats.length > 0) {
    const open = out.search(/\bports\s*:\s*\{/);
    if (open >= 0) {
      const braceIdx = out.indexOf('{', open);
      const end = findMatchingBrace(out, braceIdx);
      if (end >= 0) {
        let inner = out.slice(braceIdx, end + 1);
        for (const p of portsObjPats) inner = replaceOutsideComments(inner, new RegExp(p, 'g'), ph);
        out = out.slice(0, braceIdx) + inner + out.slice(end + 1);
      }
    }
  }
  // Env/args patterns: rewrite over the whole block.
  for (const p of blockPats) {
    out = replaceOutsideComments(out, new RegExp(p, 'g'), ph);
  }
  const changed = out.includes(ph);
  out = out.split(ph).join(String(newP));
  return { block: out, changed };
}

/**
 * Per-process-label-targeted port rewrite — the disambiguating counterpart to
 * the value-keyed `rewriteEcosystemPorts`. Each edit names the process and the
 * label (`api`/`ui`/`devUi`) to change, so a value shared by two labels in the
 * SAME block (e.g. an explicit `ports: { api: N, ui: N }` map, or a UI process
 * whose bare `PORT` is its only port) is rewritten on exactly the one the user
 * touched. An edit whose label has no rewritable literal inside the process
 * block — e.g. the value lives in an external `const PORTS = {…}` reached via
 * `ports: PORTS.server`, which this in-block rewrite can't see — is returned in
 * `unapplied` (the caller 422s) rather than falsely rewriting a same-valued env
 * literal the parser ignores. Pure (no I/O) for unit-testability.
 *
 * @param {string} content
 * @param {Array<{processName:string,label:string,oldPort:number,newPort:number}>} edits
 * @returns {{ content: string, applied: Array, unapplied: Array }}
 */
export function rewriteEcosystemPortsByProcess(content, edits) {
  const valid = (edits || []).filter(e =>
    e && typeof e.processName === 'string' && typeof e.label === 'string' &&
    Number.isInteger(e.oldPort) && Number.isInteger(e.newPort) &&
    e.oldPort > 0 && e.newPort > 0 && e.oldPort !== e.newPort);
  if (valid.length === 0) return { content, applied: [], unapplied: [] };

  const applied = [];
  const unapplied = [];

  // Group edits by process so a block is sliced once even when several labels
  // in it change (e.g. apiPort + uiPort that currently share a value).
  const byProcess = new Map();
  for (const e of valid) {
    if (!byProcess.has(e.processName)) byProcess.set(e.processName, []);
    byProcess.get(e.processName).push(e);
  }

  const blocks = [];
  for (const [name, es] of byProcess) {
    const range = findAppBlock(content, name);
    if (!range) { es.forEach(e => unapplied.push(e)); continue; }
    blocks.push({ range, edits: es });
  }
  // Rewrite back-to-front so each splice keeps earlier blocks' offsets valid.
  blocks.sort((a, b) => b.range.start - a.range.start);

  let out = content;
  for (const blk of blocks) {
    let inner = out.slice(blk.range.start, blk.range.end + 1);
    for (const e of blk.edits) {
      const r = rewriteLabelInBlock(inner, e.label, e.oldPort, e.newPort, e.processName);
      inner = r.block;
      (r.changed ? applied : unapplied).push(e);
    }
    out = out.slice(0, blk.range.start) + inner + out.slice(blk.range.end + 1);
  }

  return { content: out, applied, unapplied };
}

/**
 * Rewrite port literals in an ecosystem.config content string per a remap of
 * old → new port numbers. Pure (no I/O) so it's unit-testable.
 *
 * `ecosystem.config.cjs` is the source of truth for an app's ports — PortOS
 * *derives* uiPort/apiPort/devUiPort from it via parseEcosystemConfig. Editing
 * ports in the UI therefore has to write back here, or PM2 keeps the old ports
 * and the next config refresh re-derives them and clobbers the edit.
 *
 * Replacements are deliberately narrow so unrelated numbers (watch_delay,
 * timeouts) are never touched:
 *   1. numeric values inside a `const PORTS = {...}` block AND each per-app
 *      `ports: {...}` object (arbitrary keys — matched by value),
 *   2. `--port <n>` tokens in args strings,
 *   3. port-ish env keys (`PORT`, `*_PORT`, `VITE_PORT`) and `port:`,
 *   4. top-level port constants (`const API_PORT = <n>`),
 *   5. fallback-expression defaults (`PORT: process.env.PORT || <n>`).
 *
 * Each old value is first swapped to a unique placeholder, then placeholders
 * resolve to new values — so a remap like 6000→6001, 6001→6002 can't chain.
 * Placeholders are NUL-wrapped so index 1's token can't prefix-match index 10's.
 *
 * @param {string} content
 * @param {Map<number,number>|Array<[number,number]>} remap
 * @returns {string}
 */
export function rewriteEcosystemPorts(content, remap) {
  const pairs = (remap instanceof Map ? [...remap.entries()] : remap || [])
    .map(([o, n]) => [Number(o), Number(n)])
    .filter(([o, n]) => Number.isInteger(o) && Number.isInteger(n) && o > 0 && n > 0 && o !== n);
  if (pairs.length === 0) return content;

  const ph = (i) => `PORT_REMAP_${i}_`;
  // Port-ish env keys: PORT, FOO_PORT, VITE_PORT (and quoted variants), plus `port:`.
  const KEY = `(?:[A-Za-z][A-Za-z0-9_]*_PORT|PORT|port)`;

  // replaceOutsideComments (module scope) skips matches whose port number sits
  // inside a comment, so a commented `// PORT: 5173` never counts as a rewrite.

  let out = content;

  // 1) Within `const PORTS = {...}` and each per-app `ports: {...}` object,
  //    swap any `: <old>` value (keys there are arbitrary — API, UI, api, ui).
  //    Process regions back-to-front so each splice's offsets stay valid for
  //    the earlier (lower-index) regions still to be rewritten.
  const regions = findValuePortRegions(out).sort((a, b) => b.start - a.start);
  for (const region of regions) {
    let inner = out.slice(region.start, region.end + 1);
    pairs.forEach(([oldP], i) => {
      inner = replaceOutsideComments(inner, new RegExp(`(:\\s*)${oldP}\\b`, 'g'), ph(i));
    });
    out = out.slice(0, region.start) + inner + out.slice(region.end + 1);
  }

  // 2) `--port <old>` in args strings.
  pairs.forEach(([oldP], i) => {
    out = replaceOutsideComments(out, new RegExp(`(--port\\s+)${oldP}\\b`, 'g'), ph(i));
  });

  // 3) Port-ish key assignments anywhere (env blocks, ports objects).
  pairs.forEach(([oldP], i) => {
    out = replaceOutsideComments(out, new RegExp(`(['"\`]?\\b${KEY}\\b['"\`]?\\s*:\\s*)${oldP}\\b`, 'g'), ph(i));
  });

  // 4) Top-level port constants — `const API_PORT = 5555` / `let CDP_PORT = …`.
  //    parseEcosystemConfig derives ports from these (a `\w*PORT\w*` name `=`
  //    number), so an edit that skipped them would revert on the next refresh.
  pairs.forEach(([oldP], i) => {
    out = replaceOutsideComments(out, new RegExp(`((?:const|let|var)\\s+\\w*PORT\\w*\\s*=\\s*)${oldP}\\b`, 'g'), ph(i));
  });

  // 5) Fallback-expression defaults — `PORT: process.env.PORT || 4420`.
  //    parseEcosystemConfig resolves the `|| <n>` literal, so it must be
  //    rewritten too. The value isn't adjacent to the key (step 3 misses it),
  //    so match the port-ish key, then any same-value expression up to `||`.
  //    `[^,}\n]*?` keeps the match inside one value (no comma/brace/newline).
  pairs.forEach(([oldP], i) => {
    out = replaceOutsideComments(out, new RegExp(`(['"\`]?\\b${KEY}\\b['"\`]?\\s*:\\s*[^,}\\n]*?\\|\\|\\s*['"]?)${oldP}\\b`, 'g'), ph(i));
  });

  // Resolve placeholders → new values.
  pairs.forEach(([, newP], i) => {
    out = out.split(ph(i)).join(String(newP));
  });

  return out;
}

/**
 * Persist a port remap to an app's on-disk ecosystem config (`.cjs` preferred,
 * then `.js`). Returns `{ file, changed }`. No-op (changed:false) when nothing
 * matched. See rewriteEcosystemPorts for why this is the canonical write path.
 *
 * @param {string} repoPath
 * @param {Map<number,number>|Array<[number,number]>} remap
 */
export async function writeEcosystemPorts(repoPath, remap) {
  // Same resolution order as parseEcosystemFromPath — rewrite the file the
  // reader actually derives ports from (see ECOSYSTEM_CONFIG_FILENAMES).
  for (const name of ECOSYSTEM_CONFIG_FILENAMES) {
    const filePath = join(repoPath, name);
    if (!existsSync(filePath)) continue;
    const content = await readFile(filePath, 'utf-8');
    const updated = rewriteEcosystemPorts(content, remap);
    if (updated !== content) {
      await atomicWrite(filePath, updated);
      return { file: name, changed: true };
    }
    return { file: name, changed: false };
  }
  return { file: null, changed: false };
}

/**
 * Persist a per-process-label-targeted port remap to an app's on-disk ecosystem
 * config (`.cjs` preferred, then `.js`). The disambiguating counterpart to
 * writeEcosystemPorts: use this when a port value is shared by two labels (e.g.
 * `ports: { api: N, ui: N }`) and only one was edited. Returns
 * `{ file, changed, applied, unapplied }`; `unapplied` lists edits whose process
 * block or label literal wasn't found (caller decides whether that's a failure).
 *
 * **All-or-nothing.** The rewrite is computed in full (pure) before any I/O, and
 * the file is written ONLY when every edit applied (`unapplied` is empty). A
 * batch where some labels are rewritable and others aren't (e.g. one port is a
 * literal `PORT: 6000` but a same-valued sibling lives in an external
 * `ports: PORTS.client` reference) must NOT persist its applied subset — the
 * caller turns a non-empty `unapplied` into a 422 and skips the registry update,
 * so a partial on-disk write would leave config and registry inconsistent for a
 * request that "failed". When `unapplied` is non-empty the file is left
 * untouched and `applied` is reported empty (nothing was persisted).
 *
 * @param {string} repoPath
 * @param {Array<{processName:string,label:string,oldPort:number,newPort:number}>} edits
 */
export async function writeEcosystemPortsByProcess(repoPath, edits) {
  for (const name of ECOSYSTEM_CONFIG_FILENAMES) {
    const filePath = join(repoPath, name);
    if (!existsSync(filePath)) continue;
    const content = await readFile(filePath, 'utf-8');
    const { content: updated, applied, unapplied } = rewriteEcosystemPortsByProcess(content, edits);
    // Don't persist a partial batch: if any edit couldn't be applied, the
    // caller rejects the whole request, so writing the applied subset would
    // desync config from the (un-updated) registry.
    if (unapplied.length > 0) {
      return { file: name, changed: false, applied: [], unapplied };
    }
    if (updated !== content) {
      await atomicWrite(filePath, updated);
      return { file: name, changed: true, applied, unapplied };
    }
    return { file: name, changed: false, applied, unapplied };
  }
  return { file: null, changed: false, applied: [], unapplied: edits || [] };
}

/**
 * Persist a mixed port edit — a value-keyed `remap` (distinct ports) AND a set
 * of per-process-label-targeted `edits` (shared-value ports) — to an app's
 * ecosystem config in ONE atomic write.
 *
 * Both rewrites are computed in memory against the same file content, then the
 * file is written exactly once. This is the only way to keep a mixed edit
 * all-or-nothing: writing the value-keyed pass and the targeted pass as two
 * separate `atomicWrite`s lets the first land on disk before the second reports
 * an unpersistable edit — so a request the caller then 422s would still have
 * partially changed the config. Here, if ANY targeted edit is unapplied, the
 * file is left untouched and the whole result is reported as not-persisted, so
 * the caller's reject path never leaves a partial write behind.
 *
 * Returns `{ file, changed, remapApplied, applied, unapplied }`:
 *   - `remapApplied` — true when the value-keyed remap matched a literal
 *   - `applied`/`unapplied` — the targeted edits that did / didn't rewrite
 *
 * @param {string} repoPath
 * @param {Array<[number,number]>} remap
 * @param {Array<{processName:string,label:string,oldPort:number,newPort:number}>} edits
 */
export async function writeEcosystemPortEdits(repoPath, remap, edits) {
  const hasRemap = (remap || []).length > 0;
  const hasEdits = (edits || []).length > 0;
  if (!hasRemap && !hasEdits) return { file: null, changed: false, remapApplied: false, applied: [], unapplied: [] };

  for (const name of ECOSYSTEM_CONFIG_FILENAMES) {
    const filePath = join(repoPath, name);
    if (!existsSync(filePath)) continue;
    const content = await readFile(filePath, 'utf-8');

    // The two passes both run against the in-memory result of the other so a
    // single write reflects both — but whichever runs SECOND can match a literal
    // the first pass just created, chaining one edit into another. That happens
    // when the second pass's match-value equals a value the first produced:
    //   - value-keyed→targeted chains if a targeted OLD value equals a remap NEW
    //     value (forward collision), and
    //   - targeted→value-keyed chains if a remap OLD value equals a targeted NEW
    //     value (reverse collision).
    // Pick the order that avoids the collision present; if BOTH directions
    // collide there's no safe order, so treat the whole batch as unpersistable
    // (the caller 422s — honest, vs. silently corrupting a sibling port).
    const remapOlds = remap.map(([o]) => o);
    const remapNews = remap.map(([, n]) => n);
    const targetedOlds = (edits || []).map(e => e.oldPort);
    const targetedNews = (edits || []).map(e => e.newPort);
    const forwardCollision = hasRemap && hasEdits && targetedOlds.some(o => remapNews.includes(o));
    const reverseCollision = hasRemap && hasEdits && remapOlds.some(o => targetedNews.includes(o));

    // Both directions collide ⇒ neither single ordering is safe (a true value
    // cycle, e.g. swapping ui↔devUi between two same-block ports). Resolving it
    // would need per-edit placeholder staging; that's an exotic intra-block port
    // swap well outside the shared/derived cases this path targets, so we
    // conservatively reject (a safe 422 — no corruption) rather than build it.
    if (forwardCollision && reverseCollision) {
      return { file: name, changed: false, remapApplied: false, applied: [], unapplied: edits || [] };
    }

    let result, applied, unapplied, remapApplied;
    if (forwardCollision) {
      // Run targeted FIRST so the value-keyed pass can't feed it a fresh literal.
      const t = hasEdits ? rewriteEcosystemPortsByProcess(content, edits) : { content, applied: [], unapplied: [] };
      const afterRemap = hasRemap ? rewriteEcosystemPorts(t.content, remap) : t.content;
      result = afterRemap; applied = t.applied; unapplied = t.unapplied;
      remapApplied = hasRemap && afterRemap !== t.content;
    } else {
      // Default: value-keyed first, then targeted (safe when no forward collision).
      const afterRemap = hasRemap ? rewriteEcosystemPorts(content, remap) : content;
      const t = hasEdits ? rewriteEcosystemPortsByProcess(afterRemap, edits) : { content: afterRemap, applied: [], unapplied: [] };
      result = t.content; applied = t.applied; unapplied = t.unapplied;
      remapApplied = hasRemap && afterRemap !== content;
    }

    // Persist NOTHING when ANY part of the request is unpersistable — the caller
    // rejects the whole update (422) in either of these cases, so a partial
    // write would desync config from the un-updated registry:
    //   - a requested value-keyed remap matched no literal (`hasRemap` &&
    //     !remapApplied) — the symmetric twin of an unapplied targeted edit, and
    //   - any targeted edit couldn't be applied (`unapplied`).
    const remapFailed = hasRemap && !remapApplied;
    if (remapFailed || unapplied.length > 0) {
      return { file: name, changed: false, remapApplied: false, applied: [], unapplied };
    }

    if (result !== content) {
      await atomicWrite(filePath, result);
      return { file: name, changed: true, remapApplied, applied, unapplied };
    }
    return { file: name, changed: false, remapApplied, applied, unapplied };
  }
  return { file: null, changed: false, remapApplied: false, applied: [], unapplied: edits || [] };
}

// Each detection step mutates the shared `result` and emits its own `detect:step`
// frames. A step returning `false` means the stream must stop (validate only).

async function validateStep(socket, dirPath, result, emit) {
  emit('validate', 'running', { message: 'Validating directory path...' });

  const fail = (message) => {
    emit('validate', 'error', { message });
    socket.emit('detect:complete', { success: false, error: message });
    return false;
  };

  if (!existsSync(dirPath)) return fail('Directory does not exist');
  const stats = await stat(dirPath);
  if (!stats.isDirectory()) return fail('Path is not a directory');

  emit('validate', 'done', { message: 'Valid directory' });
  result.name = basename(dirPath);
  return true;
}

/** XcodeGen `project.yml`: name, platform-derived type, and build command. */
async function applyXcodeGenProject(dirPath, result) {
  const ymlContent = await readFile(join(dirPath, 'project.yml'), 'utf-8').catch(() => '');
  const nameMatch = ymlContent.match(/^name:\s*(.+)$/m);
  if (nameMatch) result.name = nameMatch[1].trim();

  const platformMatch = ymlContent.match(/platform:\s*\[?([^\]\n]+)/);
  const platforms = platformMatch ? platformMatch[1].toLowerCase() : '';
  if (platforms.includes('ios') && !platforms.includes('macos')) result.type = 'ios-native';
  else if (platforms.includes('macos') && !platforms.includes('ios')) result.type = 'macos-native';
  else result.type = 'xcode';

  result.buildCommand = 'xcodebuild -scheme ' + result.name + ' build';
}

/** Swift/Xcode projects are recognized from directory contents alone. */
async function detectSwiftProject(dirPath, files, result) {
  const hasXcodeproj = files.some(f => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'));
  const hasProjectYml = files.includes('project.yml');
  const hasPackageSwift = files.includes('Package.swift');
  if (!hasXcodeproj && !hasProjectYml && !hasPackageSwift) return;

  if (hasProjectYml) {
    await applyXcodeGenProject(dirPath, result);
  } else if (hasPackageSwift) {
    result.type = 'swift';
    result.buildCommand = 'swift build';
  } else {
    // .xcodeproj without project.yml
    const xcodeprojDir = files.find(f => f.endsWith('.xcodeproj'));
    const schemeName = xcodeprojDir?.replace('.xcodeproj', '') || result.name;
    result.type = 'xcode';
    result.buildCommand = 'xcodebuild -scheme ' + schemeName + ' build';
  }

  result.startCommands = [];
  result.pm2ProcessNames = [];
  result.editorCommand = process.platform === 'darwin' ? 'xed .' : 'code .';
}

/** Returns the directory entry names so later steps can reuse them. */
async function filesStep(dirPath, result, emit) {
  emit('files', 'running', { message: 'Scanning directory...' });
  const entries = await readdir(dirPath, { withFileTypes: true }).catch(() => []);
  const files = entries.map(e => e.name);
  emit('files', 'done', { message: `Found ${files.length} files`, files: files.slice(0, 20) });
  await detectSwiftProject(dirPath, files, result);
  return files;
}

function applyPackageJson(pkg, result) {
  result.name = pkg.name || result.name;
  result.description = pkg.description || '';

  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
  if (deps.vite && deps.express) result.type = 'vite+express';
  else if (deps.vite || deps.react || deps.vue) result.type = 'vite';
  else if (deps.express || deps.fastify || deps.koa) result.type = 'single-node-server';
  else if (deps.next) result.type = 'nextjs';

  const scripts = pkg.scripts || {};
  if (scripts.dev) result.startCommands.push('npm run dev');
  if (scripts.start && !scripts.dev) result.startCommands.push('npm start');
  if (scripts.build) result.buildCommand = 'npm run build';
}

async function packageStep(dirPath, files, result, emit) {
  emit('package', 'running', { message: 'Reading package.json...' });
  const pkgPath = join(dirPath, 'package.json');

  if (!existsSync(pkgPath)) {
    // No package.json ⇒ nothing Node owns this repo, so fall back to marker-file
    // classification for the common non-Node runtimes. Without this, a Python
    // service / Go binary / Docker stack / static site all landed on `unknown`
    // and were offered Node PM2 standardization. Guarded on `unknown` so an
    // Apple type already resolved in the files step (a Swift repo that also ships a
    // Dockerfile) isn't overwritten.
    const nonNodeType = result.type === 'unknown' ? classifyNonNodeType(files) : null;
    if (nonNodeType) result.type = nonNodeType;
    emit('package', 'done', {
      message: nonNodeType ? `No package.json — detected ${nonNodeType} project` : 'No package.json found',
      type: result.type
    });
    return;
  }

  const content = await tryReadFile(pkgPath);
  if (!content) return;
  const pkg = safeJSONParse(content, null);
  if (!pkg) {
    emit('package', 'error', { message: 'Invalid package.json format' });
    return;
  }
  applyPackageJson(pkg, result);
  emit('package', 'done', {
    message: `Found: ${result.name}`,
    name: result.name,
    description: result.description,
    type: result.type,
    startCommands: result.startCommands
  });
}

async function applyEnvPorts(dirPath, result, configFiles) {
  const envPath = join(dirPath, '.env');
  if (!existsSync(envPath)) return;
  const content = await readFile(envPath, 'utf-8').catch(() => '');
  const portMatch = content.match(/PORT\s*=\s*(\d+)/i);
  if (portMatch) result.apiPort = parseInt(portMatch[1], 10);
  const viteMatch = content.match(/VITE_PORT\s*=\s*(\d+)/i);
  if (viteMatch) result.devUiPort = parseInt(viteMatch[1], 10);
  configFiles.push('.env');
}

async function applyViteConfigPorts(dirPath, result, configFiles) {
  for (const viteConfig of ['vite.config.js', 'vite.config.ts']) {
    const configPath = join(dirPath, viteConfig);
    if (!existsSync(configPath)) continue;
    const content = await readFile(configPath, 'utf-8').catch(() => '');
    const portMatch = content.match(/port\s*:\s*(\d+)/);
    if (portMatch) result.devUiPort = parseInt(portMatch[1], 10);
    configFiles.push(viteConfig);
  }
}

/** Fold the parsed ecosystem processes into `result`, deriving any unset ports. */
async function applyParsedProcesses(dirPath, parsedProcesses, result) {
  // For processes that use vite and don't have a port, check their cwd for vite.config
  for (const proc of parsedProcesses) {
    const vitePort = await resolveViteConfigPortForProcess(dirPath, proc);
    if (vitePort) proc.port = vitePort;
    // Clean up internal properties
    delete proc.cwd;
    delete proc.usesVite;
  }

  result.processes = parsedProcesses;
  result.pm2ProcessNames = parsedProcesses.map(p => p.name);

  const apiProc = parsedProcesses.find(p => p.ports?.api);
  if (apiProc && !result.apiPort) result.apiPort = apiProc.ports.api;
  const uiProc = parsedProcesses.find(p => p.ports?.ui);
  if (uiProc && !result.uiPort) result.uiPort = uiProc.ports.ui;
  const devUiProc = parsedProcesses.find(p => p.ports?.devUi);
  if (devUiProc && !result.devUiPort) result.devUiPort = devUiProc.ports.devUi;
  // When app has API + Vite dev but no dedicated UI port,
  // the prod UI is served by the API server
  if (!result.uiPort && result.apiPort && result.devUiPort) result.uiPort = result.apiPort;
}

async function applyEcosystemConfig(dirPath, result, configFiles) {
  for (const ecosystemFile of ECOSYSTEM_CONFIG_FILENAMES) {
    const ecosystemPath = join(dirPath, ecosystemFile);
    if (!existsSync(ecosystemPath)) continue;
    const content = await readFile(ecosystemPath, 'utf-8').catch(() => '');
    if (!content) continue;

    const { processes: parsedProcesses, pm2Home } = parseEcosystemConfig(content);
    if (pm2Home) result.pm2Home = pm2Home;
    if (parsedProcesses.length > 0) await applyParsedProcesses(dirPath, parsedProcesses, result);

    // Extract UI port from CLIENT_URL (still needed as it's not in process configs)
    const clientUrlMatch = content.match(/CLIENT_URL\s*:\s*['"]https?:\/\/[^:]+:(\d+)/);
    if (clientUrlMatch && !result.uiPort) result.uiPort = parseInt(clientUrlMatch[1], 10);

    configFiles.push(ecosystemFile);
  }
}

async function configStep(dirPath, result, emit) {
  emit('config', 'running', { message: 'Checking configuration files...' });
  const configFiles = [];

  await applyEnvPorts(dirPath, result, configFiles);
  await applyViteConfigPorts(dirPath, result, configFiles);
  await applyEcosystemConfig(dirPath, result, configFiles);

  // When config-file heuristics found a Vite dev port but no dedicated uiPort,
  // derive uiPort: API serves prod UI if present, otherwise devUiPort is the only UI
  if (!result.uiPort && result.devUiPort) {
    result.uiPort = result.apiPort ?? result.devUiPort;
  }

  emit('config', 'done', {
    message: configFiles.length ? `Found: ${configFiles.join(', ')}` : 'No config files found',
    uiPort: result.uiPort,
    devUiPort: result.devUiPort,
    apiPort: result.apiPort,
    pm2ProcessNames: result.pm2ProcessNames.length > 0 ? result.pm2ProcessNames : undefined,
    processes: result.processes.length > 0 ? result.processes : undefined,
    configFiles
  });
}

/** Generate PM2 process names only when the ecosystem config supplied none. */
function defaultPm2ProcessNames(result) {
  const baseName = result.name.toLowerCase().replace(/[^a-z0-9]/g, '-');
  return result.type === 'vite+express' ? [`${baseName}-ui`, `${baseName}-api`] : [baseName];
}

async function pm2Step(result, emit) {
  if (!usesPm2(result.type)) {
    emit('pm2', 'skipped', { message: `Not applicable for ${result.type} apps` });
    return;
  }

  emit('pm2', 'running', { message: 'Checking PM2 processes...' });
  // `listProcessesStrict()` returns `null` when the read itself FAILED (vs
  // `[]` for a successful read with no processes) — the absent-vs-empty
  // contract from issue #968, now the one non-test owner of raw `pm2 jlist`
  // execution/parsing alongside `autofixer/shared.js` (#8164). Use custom
  // PM2_HOME if detected from ecosystem config.
  const pm2Processes = await listProcessesStrict(result.pm2Home || null);

  if (pm2Processes === null) {
    // A failed read must not be reported as "no matching processes" — that
    // would silently drop the pm2ProcessNames the ecosystem config already
    // found. Leave result.pm2Status/pm2ProcessNames as already derived and
    // surface the read failure on its own stage.
    emit('pm2', 'error', { message: 'PM2 process read failed — status is unavailable' });
    return;
  }

  // Look for processes that might be this app
  const possibleNames = [
    result.name,
    result.name.toLowerCase(),
    result.name.toLowerCase().replace(/[^a-z0-9]/g, '-'),
    `${result.name}-ui`,
    `${result.name}-api`
  ];
  const matchingProcesses = pm2Processes.filter(p =>
    possibleNames.some(name => p.name.includes(name) || name.includes(p.name))
  );

  if (matchingProcesses.length === 0) {
    emit('pm2', 'done', { message: 'No matching PM2 processes found' });
    if (result.pm2ProcessNames.length === 0) result.pm2ProcessNames = defaultPm2ProcessNames(result);
    return;
  }

  result.pm2Status = matchingProcesses.map(p => ({ name: p.name, status: p.status, pid: p.pid }));
  // Use actual found PM2 process names
  result.pm2ProcessNames = matchingProcesses.map(p => p.name);
  emit('pm2', 'done', {
    message: `Found ${matchingProcesses.length} running process(es)`,
    pm2Status: result.pm2Status,
    pm2ProcessNames: result.pm2ProcessNames
  });
}

/** Fast, no-AI description: the first non-heading, non-image README line. */
async function readmeStep(dirPath, result, emit) {
  if (result.description) {
    emit('readme', 'skipped', { message: 'Description already found in package.json' });
    return;
  }

  emit('readme', 'running', { message: 'Reading README.md...' });
  for (const readmeFile of ['README.md', 'readme.md', 'Readme.md']) {
    const readmePath = join(dirPath, readmeFile);
    if (!existsSync(readmePath)) continue;
    const content = await readFile(readmePath, 'utf-8').catch(() => '');
    if (!content) continue;
    const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('#') && !l.startsWith('!'));
    if (lines.length > 0) result.description = lines[0].trim().substring(0, 200);
    emit('readme', 'done', { message: `Found: ${readmeFile}`, description: result.description });
    return;
  }
  emit('readme', 'done', { message: 'No README found' });
}

async function iconStep(dirPath, result, emit) {
  emit('icon', 'running', { message: 'Looking for app icon...' });
  const detectedIcon = await detectAppIcon(dirPath, result.type);
  if (!detectedIcon) {
    emit('icon', 'done', { message: 'No app icon found' });
    return;
  }
  result.appIconPath = detectedIcon;
  emit('icon', 'done', { message: `Found: ${basename(detectedIcon)}`, appIconPath: detectedIcon });
}

/**
 * Stream detection results to a socket as each step completes
 */
export async function streamDetection(socket, dirPath) {
  const emit = (step, status, data = {}) => {
    socket.emit('detect:step', { step, status, data, timestamp: Date.now() });
  };

  const result = {
    name: '',
    description: '',
    uiPort: null,
    devUiPort: null,
    apiPort: null,
    buildCommand: null,
    startCommands: [],
    pm2ProcessNames: [],
    pm2Status: null,
    processes: [],
    pm2Home: null,
    type: 'unknown',
    nativeLaunch: null,
    appIconPath: null
  };

  if (!await validateStep(socket, dirPath, result, emit)) return;

  const files = await filesStep(dirPath, result, emit);
  const godotNativeLaunch = detectGodotNativeLaunch(dirPath);
  await packageStep(dirPath, files, result, emit);
  // Native game launch is additive: web ports/processes remain the standard
  // managed app while the game gets its own explicit action.
  if (godotNativeLaunch) result.nativeLaunch = godotNativeLaunch;

  await configStep(dirPath, result, emit);
  await pm2Step(result, emit);
  await readmeStep(dirPath, result, emit);
  await iconStep(dirPath, result, emit);

  socket.emit('detect:complete', { success: true, result });
}