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

35.2 KB
Raw Blame
import { readFile, writeFile, readdir, realpath } from 'fs/promises';
import { existsSync } from 'fs';
import { join, basename, relative } from 'path';
import { exec, spawn } from '../lib/childProcess.js';
import { promisify } from 'util';
import { getActiveProvider, getProviderById } from './providers.js';
import { tryReadFile } from '../lib/fileUtils.js';
import { extractJson } from '../lib/jsonExtract.js';
import { runPromptThroughProvider } from './promptRunner.js';
import { getReservedPorts, getAllApps } from './apps.js';
import { PORTOS_APP_ID } from '../lib/appIdentity.js';
import { usesPm2 } from './appProcessTypes.js';
import { isStandardizable } from './streamingDetect.js';
import { getListeningPorts } from '../lib/platform.js';
import { isBrowserUnsafePort } from '../lib/browserUnsafePorts.js';
import { DEFAULT_PORT_RANGE_START } from './ports.js';
import { isPathInsideDir } from '../lib/pathSafety.js';

// Mirrors standardizePlanStrayPortSchema (lib/validation.js): the sink re-checks
// because the socket flow applies the model's plan without the HTTP route's schema.
const STRAY_VARIABLE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;

const execAsync = promisify(exec);
const DEFAULT_PM2_AI_TIMEOUT_MS = 180000;

// Marker written into the header of every ecosystem.config.cjs PortOS generates.
// Used both to stamp our output (generateEcosystemContent) and to recognize it
// again on a later run (applyStandardization) — a file carrying this marker is
// PortOS's own and safe to regenerate; one without it is user-authored and is
// preserved unless the caller explicitly opts in to overwrite. Keep the two uses
// on this single constant so the stamp and the detection can never drift apart.
export const PORTOS_ECOSYSTEM_MARKER = 'Generated by PortOS PM2 Standardizer';

// Common Vite dev defaults — always avoided, since a developer machine almost
// always already has something on 5173 (and 5174 is Vite's auto-fallback).
const VITE_DEFAULT_PORTS = [5173, 5174];
// Collision reassignments start at the managed-app band services/ports.js
// allocates from (above the PortOS 5553–5569 band, clear of the Vite defaults).
const REASSIGN_FROM = DEFAULT_PORT_RANGE_START;

// A port the standardizer must never leave an app on, whoever proposed it:
// already taken on the host, or one browsers refuse to connect to.
const isOffLimitsPort = (port, taken) => taken.has(port) || isBrowserUnsafePort(port);

/**
 * Why an app must not be standardized, or `null` when it may be.
 *
 * Standardizing rewrites files in the target repo — it writes an
 * `ecosystem.config.cjs` and comments the ports out of `.env`/vite config — so
 * the "is this even a PM2 app?" question has to be answered before the flow
 * starts, not by whichever button happened to be rendered. Every entry point
 * that resolves an app record (the `app:standardize` socket handler and the
 * `/api/standardize/*` routes) runs this check; the Add App wizard has only a
 * repoPath, so it gates in the UI instead.
 *
 * @param {object} app The app record.
 * @returns {string|null} Refusal reason, or null if standardization is allowed.
 */
export function standardizeRefusalFor(app) {
  if (app?.id === PORTOS_APP_ID) {
    return 'PortOS manages its own ecosystem.config.cjs — that file is the canonical PORTS source and is not regenerated from an LLM analysis';
  }
  if (!usesPm2(app?.type)) {
    return `${app?.type} apps are not run under PM2, so there is no ecosystem config to standardize`;
  }
  if (!isStandardizable(app?.type)) {
    // The analysis prompt below 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. A type check, not prose.
    return `${app?.type} apps are not Node.js projects, so there is no Node ecosystem config to generate`;
  }
  return null;
}

const isPortKey = (key) => /(^|_)PORT$/i.test(key);

/**
 * A process's `ports` label map ({ ui: 5570 }) reduced to its positive-integer
 * entries — the LLM output is untrusted, and `parseEcosystemConfig` only reads
 * `\w+: digits` pairs back out of the generated file.
 */
function declaredPortEntries(proc) {
  if (!proc.ports || typeof proc.ports !== 'object' || Array.isArray(proc.ports)) return [];
  return Object.entries(proc.ports).filter(([label, value]) => /^\w+$/.test(label) && Number.isInteger(value) && value > 0);
}

/**
 * Collect every numeric port a process references — port-ish env keys, its
 * declared `ports` labels, plus a `--port N` token in its args string.
 */
function collectPortRefs(proc) {
  const refs = declaredPortEntries(proc).map(([, value]) => value);
  if (proc.env && typeof proc.env === 'object') {
    for (const [key, value] of Object.entries(proc.env)) {
      if (!isPortKey(key)) continue;
      const n = Number(value);
      if (Number.isInteger(n)) refs.push(n);
    }
  }
  if (typeof proc.args === 'string') {
    const m = proc.args.match(/--port\s+(\d+)/);
    if (m) refs.push(Number(m[1]));
  }
  return refs;
}

/**
 * Deterministically reassign any process port that collides with a taken port
 * (already-running, reserved by another PortOS app, or a Vite default) or that
 * duplicates another process in this same config. Mutates `processes` in place
 * (env port values + `--port` args) and returns the list of `[old, new]`
 * reassignments. This is the guarantee the LLM prompt can't provide on its own.
 */
/** Apply a per-process old→new port map to a process's env values and args. */
function applyProcPortRemap(proc, procRemap) {
  if (proc.env && typeof proc.env === 'object') {
    for (const [key, value] of Object.entries(proc.env)) {
      if (!isPortKey(key)) continue;
      const n = Number(value);
      if (procRemap.has(n)) proc.env[key] = procRemap.get(n);
    }
  }
  for (const [label, value] of declaredPortEntries(proc)) {
    if (procRemap.has(value)) proc.ports[label] = procRemap.get(value);
  }
  if (typeof proc.args === 'string') {
    proc.args = proc.args.replace(/(--port\s+)(\d+)/g, (full, pre, num) => {
      const n = Number(num);
      return procRemap.has(n) ? `${pre}${procRemap.get(n)}` : full;
    });
  }
}

export function reassignCollidingPorts(processes, takenPorts) {
  const taken = new Set((takenPorts || []).filter(Number.isInteger));

  // Every non-taken port referenced anywhere will be KEPT by some process, so a
  // replacement must avoid all of them up front — otherwise a colliding process
  // listed BEFORE the process that owns a valid managed-band port could be handed
  // that port (LLM output order isn't guaranteed), needlessly moving the owner.
  const keptValues = new Set();
  for (const proc of processes || []) {
    for (const value of collectPortRefs(proc)) {
      if (!isOffLimitsPort(value, taken)) keptValues.add(value);
    }
  }

  // `used` is everything off-limits to pickFree: taken + all kept values +
  // freshly assigned. `assigned` also blocks reuse within this run.
  const used = new Set([...taken, ...keptValues]);
  const assigned = new Set();
  const pickFree = () => {
    let p = REASSIGN_FROM;
    while (used.has(p) || assigned.has(p) || isBrowserUnsafePort(p)) p++;
    assigned.add(p);
    used.add(p);
    return p;
  };

  // Reassign PER PROCESS, not globally by value. Within one process a shared
  // value (env PORT + VITE_PORT + --port arg) moves together via the per-proc
  // map; but two DIFFERENT processes that both reference the same port — e.g.
  // both server PORT and client VITE_PORT at 5173 — must get DISTINCT ports, or
  // the "collision-free" guarantee fails. A process keeps its port only if it's
  // not taken and not already claimed by an earlier process; otherwise it's bumped.
  const claimed = new Set(); // non-taken values an earlier process already kept
  const reassignments = [];
  for (const proc of processes || []) {
    const procRemap = new Map(); // old -> new, scoped to this process
    for (const value of new Set(collectPortRefs(proc))) {
      if (isOffLimitsPort(value, taken) || claimed.has(value)) {
        const np = pickFree();
        procRemap.set(value, np);
        reassignments.push([value, np]);
      } else {
        claimed.add(value); // this process keeps it; a later dup will be bumped
      }
    }
    if (procRemap.size > 0) applyProcPortRemap(proc, procRemap);
  }

  return reassignments;
}

/**
 * Collect every port a registered app already holds — top-level fields plus
 * each process's `ports` map — mirroring getReservedPorts' per-app walk. Used
 * to exempt the app being re-standardized from its own "taken" set.
 */
function ownPortsOf(app) {
  const ports = [];
  if (!app) return ports;
  for (const p of [app.uiPort, app.devUiPort, app.apiPort, app.tlsPort]) ports.push(p);
  if (Array.isArray(app.processes)) {
    for (const proc of app.processes) {
      if (proc?.port) ports.push(proc.port);
      if (proc?.ports && typeof proc.ports === 'object') {
        for (const value of Object.values(proc.ports)) ports.push(value);
      }
    }
  }
  return ports.filter(Number.isInteger);
}

/**
 * Ports that must not be assigned to a freshly standardized app: everything
 * currently listening on the host, every port already reserved by another
 * PortOS-managed app, and the common Vite defaults — minus `excludePorts`, the
 * ports the app being standardized already owns (so re-standardizing keeps its
 * own valid ports instead of treating them as collisions and bumping them).
 */
async function gatherTakenPorts(excludePorts = []) {
  const [reserved, listening] = await Promise.all([
    getReservedPorts().catch(() => []),
    // Port discovery is safety-critical here: an unknown listener set must abort
    // analysis instead of being rendered as "none detected" and reassigned over.
    getListeningPorts(),
  ]);
  // Exempt the app's own ports ONLY from the reserved-app registry — so
  // re-standardizing keeps them. Do NOT exempt them from `listening`: if the
  // app is stopped and another process now holds one of its old ports, that
  // port is genuinely occupied and must stay off-limits regardless of which app
  // recorded it. (Vite defaults are likewise never exempted — moving off them
  // is the point.)
  const own = new Set(excludePorts.filter(Number.isInteger));
  const reservedMinusOwn = reserved.filter((p) => !own.has(p));
  return Array.from(new Set([...reservedMinusOwn, ...listening, ...VITE_DEFAULT_PORTS]))
    .filter(Number.isInteger)
    .sort((a, b) => a - b);
}

/**
 * Gather all config files for standardization analysis
 */
async function gatherConfigContext(dirPath) {
  const context = {
    dirName: basename(dirPath),
    hasGit: existsSync(join(dirPath, '.git')),
    packageJson: null,
    ecosystemConfig: null,
    ecosystemPath: null,
    envFiles: [],
    viteConfigs: [],
    otherConfigs: [],
    structure: { hasClient: false, hasServer: false, hasPackages: false }
  };

  // Check directory structure
  const entries = await readdir(dirPath, { withFileTypes: true }).catch(() => []);
  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);

  context.structure.hasClient = dirs.includes('client') || dirs.includes('web') || dirs.includes('frontend');
  context.structure.hasServer = dirs.includes('server') || dirs.includes('api') || dirs.includes('backend');
  context.structure.hasPackages = dirs.includes('packages');

  // Read package.json
  const pkgPath = join(dirPath, 'package.json');
  if (existsSync(pkgPath)) {
    context.packageJson = await tryReadFile(pkgPath);
  }

  // Read ecosystem.config
  for (const name of ['ecosystem.config.cjs', 'ecosystem.config.js']) {
    const path = join(dirPath, name);
    if (existsSync(path)) {
      context.ecosystemConfig = await tryReadFile(path);
      context.ecosystemPath = name;
      break;
    }
  }

  // Read .env files
  for (const name of ['.env', '.env.local', '.env.development']) {
    const path = join(dirPath, name);
    if (existsSync(path)) {
      const content = await readFile(path, 'utf-8').catch(() => '');
      context.envFiles.push({ name, path, content });
    }
  }

  // Read vite configs (root and subdirs)
  const vitePaths = [
    ['vite.config.js', dirPath],
    ['vite.config.ts', dirPath],
    ['client/vite.config.js', join(dirPath, 'client')],
    ['client/vite.config.ts', join(dirPath, 'client')],
    ['packages/web/vite.config.js', join(dirPath, 'packages/web')],
    ['packages/web/vite.config.ts', join(dirPath, 'packages/web')]
  ];

  for (const [relPath, _fullDir] of vitePaths) {
    const fullPath = join(dirPath, relPath);
    if (existsSync(fullPath)) {
      const content = await readFile(fullPath, 'utf-8').catch(() => '');
      context.viteConfigs.push({ name: relPath, path: fullPath, content });
    }
  }

  return context;
}

/**
 * Build LLM prompt for PM2 standardization analysis
 */
function buildStandardizationPrompt(context, takenPorts = []) {
  return `# PM2 Standardization Analysis

You are analyzing a Node.js application to generate a standardized PM2 ecosystem configuration.

## Project: ${context.dirName}

## Directory Structure
- Has client/web directory: ${context.structure.hasClient}
- Has server/api directory: ${context.structure.hasServer}
- Has packages/ directory: ${context.structure.hasPackages}

## Current Files

${context.packageJson ? `### package.json
\`\`\`json
${context.packageJson}
\`\`\`` : 'No package.json found'}

${context.ecosystemConfig ? `### ${context.ecosystemPath}
\`\`\`javascript
${context.ecosystemConfig}
\`\`\`` : 'No ecosystem.config found'}

${context.envFiles.length > 0 ? `### Environment Files
${context.envFiles.map(f => `#### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``).join('\n\n')}` : ''}

${context.viteConfigs.length > 0 ? `### Vite Configs
${context.viteConfigs.map(f => `#### ${f.name}\n\`\`\`javascript\n${f.content}\n\`\`\``).join('\n\n')}` : ''}

## Ports Already In Use — DO NOT ASSIGN ANY OF THESE

${takenPorts.length > 0 ? takenPorts.join(', ') : '(none detected)'}

These ports are already listening on this host, reserved by another managed app, or are common Vite defaults (5173/5174). Assigning any of them causes a collision. **Pick new ports in the 5570–5599 range** (never 6000 or any other port browsers refuse to connect to) instead of the framework defaults found in vite.config/.env, even when a config file suggests otherwise.

## PM2 Standard Requirements

1. **All ports MUST be in ecosystem.config.cjs env blocks** - Never in .env or vite.config
2. **Use CommonJS format** (.cjs extension) for PM2 compatibility
3. **Process naming**: lowercase-hyphenated (e.g., "myapp-server", "myapp-client")
4. **Server processes**: Enable watch for live-reload on dist/ or src/
5. **Vite processes**: Use \`npx vite --host --port XXXX\` in args, disable watch (Vite has HMR)
6. **Set cwd** for each process pointing to its directory
7. **Include NODE_ENV** in all env blocks
8. **UI vs Dev UI ports**: When the API server serves the production build of the frontend (Express static files), the production UI port equals the API port. The Vite dev server port is a separate "dev UI" port only used during development. Label Vite dev ports as UI or DEV_UI in the PORTS object (both conventions are acceptable).
9. **Port labels**: Give every process that listens on a port a \`ports\` object naming what it serves — \`{ "ui": N }\` for a process that serves HTML to a browser (a static file server, Vite, Next, an Express app serving a built frontend), \`{ "api": N }\` for a JSON/API-only server, \`{ "devUi": N }\` for a Vite dev server that sits beside an API process. The same number stays in env \`PORT\`. Without the label PortOS assumes a bare \`PORT\` is an API and the app gets no Open button.

## Output Format

Return ONLY valid JSON (no markdown wrapper, no explanation) with this structure:
{
  "processes": [
    {
      "name": "string - process name",
      "cwd": "string - relative path like ./server or ./packages/web",
      "script": "string - entry point or npx",
      "args": "string or null - for vite: 'vite --host --port XXXX'",
      "watch": "array of paths to watch or false",
      "watchDelay": 1000,
      "ignoreWatch": ["node_modules", "data", "*.log"],
      "ports": { "ui|api|devUi": "number - the same port as env.PORT, labeled by what the process serves" },
      "env": {
        "NODE_ENV": "development",
        "PORT": "number - the port this process uses"
      }
    }
  ],
  "strayPorts": [
    {
      "file": "string - relative file path",
      "variable": "string - variable name like PORT",
      "value": "number - the port value",
      "line": "number - line number",
      "action": "remove or keep"
    }
  ],
  "reasoning": "Brief explanation of your analysis"
}

Rules:
- Generate ecosystem.config.cjs content for ALL processes needed
- If existing ecosystem.config exists, preserve working configurations but add missing ports to env
- Mark PORT/VITE_PORT in .env files with action: "remove" (will be moved to ecosystem)
- Mark port in vite.config with action: "remove" (will use --port arg instead)
- If no ports are detected, use sensible defaults (3000 for frontend, 3001 for backend)`;
}

/**
 * Execute LLM analysis through the central handler — works for cli, api,
 * and tui providers without per-type branching. `cwd` is the analyzed
 * repo path, NOT PortOS's cwd; without it the CLI/TUI spawn lands in
 * PortOS's directory and the analysis reads the wrong files.
 */
async function executeAnalysis(provider, prompt, cwd) {
  const { text } = await runPromptThroughProvider({
    provider, prompt, source: 'pm2-standardize',
    timeout: provider.timeout || DEFAULT_PM2_AI_TIMEOUT_MS,
    cwd,
  });
  return text;
}

/**
 * Parse LLM response to extract JSON
 */
function parseAnalysisResponse(response, promptToStrip = '') {
  const source = promptToStrip && typeof response === 'string' && response.includes(promptToStrip)
    ? response.replace(promptToStrip, '')
    : response;
  if (typeof source === 'string' && /^\s*(?:```(?:json)?\s*)?\[/.test(source)) {
    throw new Error('Failed to parse LLM analysis response: expected an object');
  }
  const { value, lastError } = extractJson(source, {
    // The standardization prompt contains a JSON schema example; avoid the
    // first fenced block heuristic and select the process-plan shape.
    skipInnerFence: true,
    shapePredicate: (candidate) => candidate && typeof candidate === 'object'
      && !Array.isArray(candidate) && Array.isArray(candidate.processes),
  });
  // Preserve the legacy parser's falsy-value failure contract (null, false,
  // zero, and empty strings are not usable analysis objects).
  if (!value) {
    throw new Error(`Failed to parse LLM analysis response${lastError ? `: ${lastError.message}` : ''}`);
  }
  return value;
}

/**
 * Generate ecosystem.config.cjs content from processes
 */
const IDENTIFIER_KEY_RE = /^[A-Za-z_$][\w$]*$/;

/** A JS object literal with unquoted identifier keys; every other token is JSON-encoded. */
function jsObjectLiteral(value, depth = 1) {
  const pad = '  '.repeat(depth);
  const close = '  '.repeat(depth - 1);
  if (Array.isArray(value)) {
    return value.length === 0 ? '[]' : `[\n${value.map((item) => `${pad}${jsObjectLiteral(item, depth + 1)}`).join(',\n')}\n${close}]`;
  }
  if (value !== null && typeof value === 'object') {
    const entries = Object.entries(value).filter(([, item]) => item !== undefined);
    if (entries.length === 0) return '{}';
    return `{\n${entries.map(([key, item]) => `${pad}${IDENTIFIER_KEY_RE.test(key) ? key : JSON.stringify(key)}: ${jsObjectLiteral(item, depth + 1)}`).join(',\n')}\n${close}}`;
  }
  return JSON.stringify(value) ?? 'null';
}

function generateEcosystemContent(processes, appName) {
  const apps = processes.map(proc => {
    const config = {
      name: proc.name,
      cwd: proc.cwd,
      script: proc.script
    };

    if (proc.args) {
      config.args = proc.args;
    }

    if (proc.watch && proc.watch !== false) {
      config.watch = proc.watch;
      config.watch_delay = proc.watchDelay || 1000;
      config.ignore_watch = proc.ignoreWatch || ['node_modules', 'data', '*.log'];
    } else {
      config.watch = false;
    }

    const labeledPorts = declaredPortEntries(proc);
    if (labeledPorts.length > 0) {
      config.ports = Object.fromEntries(labeledPorts);
    }

    config.env = proc.env || { NODE_ENV: 'development' };

    return config;
  });

  // PM2 `require()`s this file and parseEcosystemConfig (streamingDetect.js)
  // reads it back with regexes keyed on bare `name:` / `ports:` / `env:` keys,
  // so the literal keeps identifier keys unquoted. Every value is model output
  // steered by the scanned repository: strings are JSON-encoded (the old quote
  // rewrite left `'` free to close the string and run code on load) and a key
  // that is not an identifier is quoted the same way.
  return `// PM2 Ecosystem Configuration
// ${PORTOS_ECOSYSTEM_MARKER}

module.exports = ${jsObjectLiteral({ apps })};
`;
}

/**
 * Create git backup before modifications.
 * Refuses to proceed if the working tree has uncommitted changes to avoid data loss.
 */
export async function createGitBackup(repoPath) {
  // Check if git repo
  if (!existsSync(join(repoPath, '.git'))) {
    return { success: false, reason: 'Not a git repository' };
  }

  // Refuse to overwrite uncommitted changes
  const { stdout: statusOut } = await execAsync('git status --porcelain', { cwd: repoPath });
  if (statusOut.trim()) {
    return { success: false, code: 'DIRTY_WORKTREE', reason: 'Working tree has uncommitted changes — commit or discard them before standardizing' };
  }

  const timestamp = Date.now();
  const branch = `portos-backup-${timestamp}`;

  // Create backup branch from current HEAD (captures committed state without stashing)
  // Use spawn with shell:false to avoid shell injection via branch name
  await new Promise((resolve, reject) => {
    const proc = spawn('git', ['branch', branch], { cwd: repoPath, shell: false });
    let stderr = '';
    proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
    proc.on('close', (code) => code === 0 ? resolve() : reject(new Error(`git branch failed: ${stderr.trim()}`)));
    proc.on('error', reject);
  });

  return { success: true, branch };
}

/**
 * Analyze app and generate standardization plan
 */
export async function analyzeApp(repoPath, providerId = null) {
  if (!existsSync(repoPath)) {
    return { success: false, error: 'Directory does not exist' };
  }

  // Get provider
  const provider = providerId
    ? await getProviderById(providerId)
    : await getActiveProvider();

  if (!provider) {
    return { success: false, error: 'No AI provider configured' };
  }

  if (!provider.enabled) {
    return { success: false, error: 'AI provider is disabled' };
  }

  // Gather context + the set of ports we must steer the LLM away from. Exempt
  // the app's own current ports (matched by repoPath) so re-standardizing a
  // registered app doesn't treat its valid ports as collisions and bump them.
  const context = await gatherConfigContext(repoPath);
  const ownApp = (await getAllApps().catch(() => [])).find((a) => a.repoPath === repoPath);
  const takenPorts = await gatherTakenPorts(ownPortsOf(ownApp));
  const prompt = buildStandardizationPrompt(context, takenPorts);

  // Execute analysis
  const startTime = Date.now();
  console.log(`🤖 Running ${provider.type} analysis via ${provider.name} (timeout: ${(provider.timeout || 180000) / 1000}s)`);

  const response = await executeAnalysis(provider, prompt, repoPath);

  console.log(`✅ Analysis response received in ${((Date.now() - startTime) / 1000).toFixed(1)}s`);

  // Parse response
  const analysis = parseAnalysisResponse(response, prompt);

  // Deterministic safety net: even if the LLM ignored the avoid-list, remap any
  // port that still collides with a taken/duplicate port before generating the file.
  const portReassignments = reassignCollidingPorts(analysis.processes, takenPorts);
  if (portReassignments.length > 0) {
    console.log(`🔧 PM2 standardizer reassigned colliding ports: ${portReassignments.map(([o, n]) => `${o}→${n}`).join(', ')}`);
  }

  // Generate ecosystem content
  const ecosystemContent = generateEcosystemContent(analysis.processes, context.dirName);

  return {
    success: true,
    provider: provider.name,
    repoPath,
    currentState: {
      hasEcosystem: !!context.ecosystemConfig,
      ecosystemPath: context.ecosystemPath,
      hasGit: context.hasGit,
      envFiles: context.envFiles.map(f => f.name),
      viteConfigs: context.viteConfigs.map(f => f.name)
    },
    proposedChanges: {
      createEcosystem: !context.ecosystemConfig,
      ecosystemContent,
      processes: analysis.processes,
      strayPorts: analysis.strayPorts || [],
      portReassignments: portReassignments.map(([from, to]) => ({ from, to }))
    },
    llmAnalysis: {
      providerId: provider.id,
      reasoning: analysis.reasoning || 'Analysis complete'
    }
  };
}

/**
 * Apply standardization changes to the repository
 */
export async function applyStandardization(
  repoPath,
  plan,
  { skipBackup = false, overwriteEcosystem = false } = {}
) {
  const results = {
    success: true,
    backupBranch: null,
    filesModified: [],
    filesPreserved: [],
    errors: []
  };

  // Create git backup first — abort if working tree is dirty (skip when caller already did it)
  if (plan.currentState.hasGit && !skipBackup) {
    const backup = await createGitBackup(repoPath);
    if (backup.success) {
      results.backupBranch = backup.branch;
      console.log(`📦 Created backup branch: ${backup.branch}`);
    } else {
      console.log(`⚠️ Could not create backup: ${backup.reason}`);
      if (backup.code === 'DIRTY_WORKTREE') {
        return { success: false, error: backup.reason, filesModified: [], errors: [backup.reason] };
      }
    }
  }

  // Write ecosystem.config.cjs — but never silently clobber a user-authored one.
  // A file carrying our marker is PortOS's own output and safe to regenerate; a
  // file without it (hand-written, or another tool's) is preserved unless the
  // caller explicitly opted in via `overwriteEcosystem`. Re-read from disk here
  // rather than trusting the plan's `hasEcosystem` — the file may have appeared
  // or changed between analyze and apply, and a read failure fails safe toward
  // preserving. This is what stops "standardize an app" from destroying a custom
  // config (its ports/settings) without an explicit go-ahead.
  const ecosystemPath = join(repoPath, 'ecosystem.config.cjs');
  const ecosystemExists = existsSync(ecosystemPath);
  const existingEcosystem = ecosystemExists ? await tryReadFile(ecosystemPath) : null;
  const isPortOSGenerated =
    !!existingEcosystem && existingEcosystem.includes(PORTOS_ECOSYSTEM_MARKER);
  const preserveEcosystem = ecosystemExists && !isPortOSGenerated && !overwriteEcosystem;

  if (preserveEcosystem) {
    results.filesPreserved.push('ecosystem.config.cjs');
    console.log(
      '⏭️  Preserved existing ecosystem.config.cjs (not PortOS-generated; pass overwriteEcosystem to regenerate)'
    );
  } else {
    await writeFile(ecosystemPath, plan.proposedChanges.ecosystemContent, 'utf-8');
    results.filesModified.push('ecosystem.config.cjs');
    console.log(`✅ Written ecosystem.config.cjs`);
  }

  // Remove old ecosystem.config.js if we're creating .cjs
  const oldEcosystemJs = join(repoPath, 'ecosystem.config.js');
  if (existsSync(oldEcosystemJs) && plan.proposedChanges.createEcosystem) {
    const { unlink } = await import('fs/promises');
    await unlink(oldEcosystemJs).catch(() => null);
    results.filesModified.push('ecosystem.config.js (removed)');
  }

  // Process stray ports - remove from .env files. Skip entirely when we preserved
  // the user's ecosystem: pulling ports out of their .env/vite.config only makes
  // sense once PortOS's generated ecosystem owns them, so leave the user's ports
  // wherever they put them.
  for (const stray of preserveEcosystem ? [] : plan.proposedChanges.strayPorts || []) {
    if (stray.action !== 'remove') continue;

    // Contain both model-chosen fields at the sink: the file must resolve
    // inside the repository (after following symlinks, so a planted `.env`
    // link cannot aim the write at a host file) and the variable must be a
    // bare identifier before it becomes a RegExp.
    const filePath = join(repoPath, String(stray.file ?? ''));
    if (!existsSync(filePath)) continue;
    const [realFile, realRepo] = await Promise.all([realpath(filePath).catch(() => null), realpath(repoPath).catch(() => null)]);
    if (!realFile || !realRepo || !isPathInsideDir(realRepo, realFile) || !STRAY_VARIABLE_RE.test(String(stray.variable ?? ''))) {
      console.warn(`⚠️ PM2 standardizer skipped a stray-port edit outside the plan contract: ${stray.file} / ${stray.variable}`);
      continue;
    }

    const content = await tryReadFile(filePath);
    if (!content) continue;

    // Remove the port line from .env files
    if (stray.file.includes('.env')) {
      const lines = content.split('\n');
      const filtered = lines.filter(line => {
        const trimmed = line.trim();
        if (trimmed.startsWith('#')) return true;
        return !new RegExp(`^${stray.variable}\\s*=`).test(trimmed);
      });

      if (filtered.length !== lines.length) {
        await writeFile(filePath, filtered.join('\n'), 'utf-8');
        results.filesModified.push(`${stray.file} (removed ${stray.variable})`);
        console.log(`✅ Removed ${stray.variable} from ${stray.file}`);
      }
    }

    // Remove port from vite.config (more complex - comment it out)
    if (stray.file.includes('vite.config')) {
      const modified = content.replace(
        /(\s*port\s*:\s*\d+\s*,?)/g,
        '/* $1 */ // Moved to PM2 ecosystem.config.cjs'
      );

      if (modified !== content) {
        await writeFile(filePath, modified, 'utf-8');
        results.filesModified.push(`${stray.file} (commented out port)`);
        console.log(`✅ Commented out port in ${stray.file}`);
      }
    }
  }

  return results;
}

/**
 * Run the full PM2 standardization flow: analyze → git backup → apply.
 *
 * This is the orchestration the `standardize:start` socket handler used to do
 * inline. Pulling it into the service makes it unit-testable and HTTP-callable —
 * the caller only supplies progress callbacks and consumes the final result.
 *
 * Progress is reported through `onStep({ step, status, data })` (the same
 * `step`/`status`/`data` triple the socket layer forwards as `standardize:step`)
 * and `onAnalyzed({ plan })` once the analysis plan is ready. Both callbacks are
 * optional, so the flow is callable headless.
 *
 * Resolves to the terminal outcome the caller should report as
 * `standardize:complete`:
 *   - `{ success: false, error }` on any failed step
 *   - `{ success: true, result: { backupBranch, filesModified, processes } }`
 *
 * @param {string} repoPath - Absolute path to the repo being standardized
 * @param {string|null} providerId - Optional AI provider id (else the active one)
 * @param {object} [opts]
 * @param {(evt: {step: string, status: string, data: object}) => void} [opts.onStep]
 * @param {(evt: {plan: object}) => void} [opts.onAnalyzed]
 * @param {boolean} [opts.overwriteEcosystem] - Explicit opt-in to overwrite an
 *   existing, non-PortOS-generated ecosystem.config.cjs. Default false preserves
 *   a user-authored config (see applyStandardization).
 * @param {Function} [opts.analyze] - Injectable step impl (defaults to analyzeApp);
 *   a test seam so the orchestration is unit-testable without real AI analysis.
 * @param {Function} [opts.backup] - Injectable step impl (defaults to createGitBackup).
 * @param {Function} [opts.apply] - Injectable step impl (defaults to applyStandardization).
 * @returns {Promise<{success: boolean, error?: string, result?: object}>}
 */
export async function runStandardizeFlow(
  repoPath,
  providerId = null,
  {
    onStep,
    onAnalyzed,
    overwriteEcosystem = false,
    analyze = analyzeApp,
    backup = createGitBackup,
    apply = applyStandardization
  } = {}
) {
  const emit = (step, status, data = {}) => onStep?.({ step, status, data });

  // Step 1: Analyze
  emit('analyze', 'running', { message: 'Analyzing project configuration...' });

  const analysis = await analyze(repoPath, providerId)
    .catch(err => ({ success: false, error: err.message }));

  if (!analysis.success) {
    emit('analyze', 'error', { message: analysis.error });
    return { success: false, error: analysis.error };
  }

  emit('analyze', 'done', {
    message: `Found ${analysis.proposedChanges.processes?.length || 0} processes`,
    processes: analysis.proposedChanges.processes,
    strayPorts: analysis.proposedChanges.strayPorts
  });

  onAnalyzed?.({ plan: analysis });

  // Step 2: Backup
  emit('backup', 'running', { message: 'Creating git backup...' });

  const backupResult = await backup(repoPath)
    .catch(err => ({ success: false, reason: err.message }));

  if (backupResult.success) {
    emit('backup', 'done', { message: `Backup branch: ${backupResult.branch}`, branch: backupResult.branch });
  } else if (backupResult.code === 'DIRTY_WORKTREE') {
    emit('backup', 'error', { message: backupResult.reason });
    return { success: false, error: backupResult.reason };
  } else {
    emit('backup', 'skipped', { message: backupResult.reason || 'No git repository' });
  }

  // Step 3: Apply changes (backup already handled above)
  emit('apply', 'running', { message: 'Writing ecosystem.config.cjs...' });

  const result = await apply(repoPath, analysis, { skipBackup: true, overwriteEcosystem })
    .catch(err => ({ success: false, errors: [err.message] }));

  if (result.errors?.length > 0) {
    emit('apply', 'error', { message: result.errors.join(', ') });
    return { success: false, error: result.errors.join(', ') };
  }

  const preserved = result.filesPreserved || [];
  emit('apply', 'done', {
    message: preserved.length
      ? `Modified ${result.filesModified.length} files, preserved ${preserved.length}`
      : `Modified ${result.filesModified.length} files`,
    filesModified: result.filesModified,
    filesPreserved: preserved
  });

  console.log(`✅ Standardization complete: ${result.filesModified.length} files modified`);

  return {
    success: true,
    result: {
      // Use the backup branch from step 2 since step 3 skipped its own backup.
      backupBranch: backupResult.branch || null,
      filesModified: result.filesModified,
      filesPreserved: preserved,
      processes: analysis.proposedChanges.processes
    }
  };
}

/**
 * Get the standard PM2 template for reference
 */
export function getStandardTemplate() {
  return `// PM2 Ecosystem Configuration Template
// All ports should be defined here, not in .env or vite.config

// Port definitions as single source of truth
const PORTS = {
  API: 3001,       // Express API server (also serves prod UI build)
  UI: 3000         // Vite dev server (development only)
};

module.exports = {
  PORTS,
  apps: [
    {
      name: 'myapp-server',
      cwd: './server',
      script: 'dist/index.js',
      watch: ['dist'],
      watch_delay: 1000,
      ignore_watch: ['node_modules', 'data', '*.log'],
      env: {
        NODE_ENV: 'development',
        PORT: PORTS.API
      }
    },
    {
      name: 'myapp-client',
      cwd: './client',
      script: 'npx',
      args: 'vite --host --port ' + PORTS.UI,
      watch: false,
      env: {
        NODE_ENV: 'development',
        // VITE_PORT is a PortOS convention for port discovery (read by streamingDetect/detect), not consumed by Vite itself
        VITE_PORT: PORTS.UI
      }
    }
  ]
};
`;
}

export const __testing = { generateEcosystemContent };