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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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 };