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
/**
* The Node.js runtime PortOS runs on: what it is, whether a newer stable or
* security release exists, and the in-place update through nvm.
*
* Node ships security releases often enough that "which Node is PortOS on?"
* has to be answerable from the UI, and answering it from a terminal is
* misleading: pm2 resolves `interpreter: 'node'` against the DAEMON's PATH, so
* the running server can be on a different Node than `node -v` or nvm's
* default. Everything here reads the running process (`process.version`) and
* the daemon's own report rather than PATH.
*
* An update never mutates a live runtime. It installs the target with nvm,
* aligns that Node's global pm2 CLI with the version PortOS ships, pins
* `PORTOS_NODE_INTERPRETER` (lib/nodeInterpreterPin.js), and only then hands
* off to the ordinary self-update lifecycle (`startPortosSelfUpdate`, mode
* `refresh`). That lifecycle already owns everything a runtime switch needs:
* the restart refusals, the update lock, rebuilding native modules on the new
* Node (launchUpdate puts the pin first on PATH), the daemon reload
* (pm2-daemon-refresh.js compares the daemon's Node with the pin), and the
* `pm2 delete` + `pm2 start` that makes pm2 read the new interpreter.
*
* The boot script (`pm2 startup`) needs sudo, so it is reported with the exact
* command to run, never run from here.
*/
import { existsSync, readdirSync, readFileSync } from 'fs';
import { homedir, userInfo } from 'os';
// nvm, launchd and systemd paths are POSIX-only; Windows never reaches an update.
import { posix } from 'path';
import { ServerError } from '../lib/errorHandler.js';
import { PATHS, atomicWrite } from '../lib/fileUtils.js';
import { runStreamingCommand } from '../lib/streamingSpawn.js';
import { withoutServerSecretsEnv } from '../lib/processEnv.js';
import {
NODE_INTERPRETER_ENV_KEY,
resolvePinnedNodeInterpreter,
withNodeBinOnPath,
} from '../lib/nodeInterpreterPin.js';
import { readPortosEnvValue, upsertPortosEnvLine } from '../lib/portosEnv.js';
import {
SUPPORTED_NODE_RANGE,
compareVersions,
satisfiesVersionRequirement,
} from '../../scripts/checkNodeVersion.js';
const IS_WIN = process.platform === 'win32';
const { dirname, join } = posix;
const VERSION_RE = /^v\d+\.\d+\.\d+$/;
const NODE_INDEX_URL = 'https://nodejs.org/dist/index.json';
const PM2_LATEST_URL = 'https://registry.npmjs.org/pm2/latest';
const FETCH_TIMEOUT_MS = 10_000;
const LATEST_TTL_MS = 6 * 60 * 60 * 1000;
const LATEST_ERROR_TTL_MS = 10 * 60 * 1000;
const NVM_INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
const NPM_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
// Homebrew's nvm formula ships nvm.sh outside NVM_DIR, which then holds only
// versions/ and alias/.
const NVM_SCRIPT_CANDIDATES = [
'/opt/homebrew/opt/nvm/nvm.sh',
'/usr/local/opt/nvm/nvm.sh',
'/home/linuxbrew/.linuxbrew/opt/nvm/nvm.sh',
];
/** nvm's directory and loader script, or null when nvm is not installed. */
function resolveNvm({ env = process.env, exists = existsSync, home = homedir() } = {}) {
const dir = env.NVM_DIR || join(home, '.nvm');
if (!exists(dir)) return null;
const script = [join(dir, 'nvm.sh'), ...NVM_SCRIPT_CANDIDATES].find((candidate) => exists(candidate));
return script ? { dir, script } : null;
}
const nvmNodeBinary = (dir, version) => join(dir, 'versions', 'node', version, 'bin', 'node');
function listNvmVersions(dir) {
let entries = [];
try {
entries = readdirSync(join(dir, 'versions', 'node'));
} catch {
return [];
}
return entries.filter((name) => VERSION_RE.test(name)).sort((a, b) => compareVersions(b, a));
}
/** nvm's default alias when it names an exact version; `lts/*`-style aliases read as null. */
function readNvmDefault(dir) {
let alias = '';
try {
alias = readFileSync(join(dir, 'alias', 'default'), 'utf8').trim();
} catch {
return null;
}
const version = alias.startsWith('v') ? alias : `v${alias}`;
return VERSION_RE.test(version) ? version : null;
}
/** Where a node binary came from, for the label next to its version. */
function classifyNodeSource(execPath, nvmDir) {
const path = String(execPath || '');
if (nvmDir && path.startsWith(join(nvmDir, 'versions', 'node'))) return 'nvm';
if (/\/(homebrew|linuxbrew|Cellar)\//.test(path)) return 'homebrew';
return 'other';
}
/**
* The update choices for a running version, from nodejs.org's release index.
*
* Offers the newest release on the running major line (the security patch),
* the newest LTS, and the newest release overall, each only when it is newer
* than what runs and inside PortOS's supported range. `securityUpdate` is true
* when a release newer than the running one on its own line is flagged as a
* security release.
*/
function summarizeNodeReleases(releases, runningVersion) {
const supported = (Array.isArray(releases) ? releases : [])
.filter((release) => VERSION_RE.test(release?.version || ''))
.filter((release) => satisfiesVersionRequirement(release.version, SUPPORTED_NODE_RANGE) === true)
.sort((a, b) => compareVersions(b.version, a.version));
const major = (version) => Number(version.slice(1).split('.')[0]);
const runningMajor = major(runningVersion);
const newer = (release) => compareVersions(release.version, runningVersion) > 0;
const latestInLine = supported.find((release) => major(release.version) === runningMajor) || null;
const latestLts = supported.find((release) => release.lts) || null;
const latestCurrent = supported[0] || null;
const securityUpdate = supported.some((release) => release.security && newer(release) && major(release.version) === runningMajor);
const offers = [];
const offer = (release, label) => {
if (!release || !newer(release) || offers.some((entry) => entry.version === release.version)) return;
offers.push({
version: release.version,
label,
lts: release.lts ? String(release.lts) : null,
date: release.date || null,
});
};
offer(latestInLine, `Latest ${runningMajor}.x`);
offer(latestLts, 'Latest LTS');
offer(latestCurrent, 'Latest release');
const pick = (release) => (release ? { version: release.version, lts: release.lts ? String(release.lts) : null, date: release.date || null } : null);
return {
latestInLine: pick(latestInLine),
latestLts: pick(latestLts),
latestCurrent: pick(latestCurrent),
securityUpdate,
offers,
};
}
// nodejs.org's index and npm's pm2 dist-tag, cached. `value: null` is the
// not-fetched sentinel; a failure backs off for the short TTL instead of
// poisoning the cache or refetching on every panel load.
const caches = { node: { value: null, fetchedAt: 0 }, pm2: { value: null, fetchedAt: 0 } };
function resetNodeRuntimeCaches() {
caches.node = { value: null, fetchedAt: 0 };
caches.pm2 = { value: null, fetchedAt: 0 };
}
async function cachedFetch(key, url, pickValue) {
const entry = caches[key];
const age = Date.now() - entry.fetchedAt;
if (entry.value && age < LATEST_TTL_MS) return entry.value;
if (!entry.value && entry.fetchedAt && age < LATEST_ERROR_TTL_MS) return null;
const value = await fetch(url, {
headers: { 'User-Agent': 'PortOS', Accept: 'application/json' },
signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
}).then((res) => (res.ok ? res.json() : null)).then((body) => (body ? pickValue(body) : null)).catch(() => null);
caches[key] = { value, fetchedAt: Date.now() };
return value;
}
const getNodeReleaseIndex = () => cachedFetch('node', NODE_INDEX_URL, (body) => (Array.isArray(body) ? body : null));
const getLatestPm2Version = () => cachedFetch('pm2', PM2_LATEST_URL, (body) => (typeof body?.version === 'string' ? body.version : null));
function readPackageVersion(packageJsonPath) {
try {
const version = JSON.parse(readFileSync(packageJsonPath, 'utf8')).version;
return typeof version === 'string' ? version : null;
} catch {
return null;
}
}
/** The pm2 PortOS ships (its pinned root dependency). */
const shippedPm2Version = () => readPackageVersion(join(PATHS.root, 'node_modules', 'pm2', 'package.json'));
/**
* npm's global prefix for a node binary. Homebrew runs node from its Cellar
* keg (`<brew>/Cellar/node/<v>/bin/node`) while globals live under `<brew>`;
* nvm and official installs keep them beside the binary's own `bin/`.
*/
function nodeGlobalPrefix(nodeBinary) {
const cellar = nodeBinary.indexOf('/Cellar/');
return cellar > 0 ? nodeBinary.slice(0, cellar) : dirname(dirname(nodeBinary));
}
/** The global pm2 CLI installed for a node binary, or null. */
function globalPm2Version(nodeBinary) {
if (!nodeBinary || IS_WIN) return null;
return readPackageVersion(join(nodeGlobalPrefix(nodeBinary), 'lib', 'node_modules', 'pm2', 'package.json'));
}
const NVM_BIN_SEGMENT = /(\/\.nvm\/versions\/node\/)v\d+\.\d+\.\d+(\/bin)/g;
const nvmVersionOf = (binDir) => binDir.match(/\/\.nvm\/versions\/node\/(v\d+\.\d+\.\d+)\/bin$/)?.[1] || null;
/**
* A launchd agent's nvm Node paths moved to `binDir`'s version, or null when
* there is nothing PortOS can safely rewrite: the target is not an nvm Node,
* or the agent names no nvm Node at all (pm2 startup generated it elsewhere).
*/
function rewriteLaunchAgent(contents, binDir) {
const version = nvmVersionOf(binDir);
if (!version || typeof contents !== 'string' || !NVM_BIN_SEGMENT.test(contents)) return null;
NVM_BIN_SEGMENT.lastIndex = 0;
return contents.replace(NVM_BIN_SEGMENT, `$1${version}$2`);
}
function startupFileFor(system, home, user) {
return system === 'launchd'
? join(home, 'Library', 'LaunchAgents', `pm2.${user}.plist`)
: `/etc/systemd/system/pm2-${user}.service`;
}
/**
* Whether the boot-time `pm2 resurrect` still runs from an older Node. A macOS
* LaunchAgent lives in the user's own Library, so PortOS can repoint its nvm
* paths itself (`fixable`); anything else gets the sudo command that
* regenerates it. Null where PortOS can't tell (Windows, no supported init).
*/
function getStartupStatus({ nodeBinary, platform = process.platform, home = homedir(), user = safeUserName(), readText = readTextOrNull } = {}) {
const system = platform === 'darwin' ? 'launchd' : platform === 'linux' ? 'systemd' : null;
if (!system || !nodeBinary || !user) return null;
const binDir = dirname(nodeBinary);
const globalBin = join(nodeGlobalPrefix(nodeBinary), 'bin');
const contents = readText(startupFileFor(system, home, user));
const current = contents === null ? null : contents.includes(binDir) || contents.includes(globalBin);
return {
system,
configured: contents !== null,
current,
fixable: system === 'launchd' && current === false && rewriteLaunchAgent(contents, binDir) !== null,
command: `sudo env PATH=$PATH:${binDir} ${join(globalBin, 'pm2')} startup ${system} -u ${user} --hp ${home}`,
};
}
/**
* Repoint the LaunchAgent at `nodeBinary`'s nvm version. Takes effect at the
* next login; nothing is restarted.
* @returns {Promise<(() => Promise<void>)|null>} an undo that writes the
* previous agent back, or null when nothing was rewritten
*/
export async function repairStartup(nodeBinary = resolvePinnedNodeInterpreter() || process.execPath) {
const user = safeUserName();
const status = getStartupStatus({ nodeBinary, user });
if (!status?.fixable) return null;
const file = startupFileFor(status.system, homedir(), user);
const previous = readTextOrNull(file);
const next = rewriteLaunchAgent(previous, dirname(nodeBinary));
if (next === null) return null;
await atomicWrite(file, next);
return () => atomicWrite(file, previous);
}
function safeUserName() {
try {
return userInfo().username;
} catch {
return null;
}
}
function readTextOrNull(file) {
try {
return readFileSync(file, 'utf8');
} catch {
return null;
}
}
async function readDaemonIdentity() {
const { getDaemonIdentity } = await import('./pm2.js');
return getDaemonIdentity().catch(() => null);
}
/** Everything the Node runtime panel renders. */
export async function getNodeRuntimeStatus() {
const nvm = IS_WIN ? null : resolveNvm();
const running = process.version;
const pinned = resolvePinnedNodeInterpreter();
const [releases, latestPm2, daemon] = await Promise.all([
getNodeReleaseIndex(),
getLatestPm2Version(),
readDaemonIdentity(),
]);
const summary = releases ? summarizeNodeReleases(releases, running) : null;
const shipped = shippedPm2Version();
const cliNode = pinned || process.execPath;
const cli = globalPm2Version(cliNode);
const blockedReason = IS_WIN
? 'Updating Node from PortOS needs nvm, which is not available on Windows. Update Node with your installer, then update PortOS.'
: !nvm
? 'nvm is not installed. Install nvm (https://github.com/nvm-sh/nvm) to update Node from PortOS.'
: null;
// Behind, not merely different: a newer pm2 someone installed globally is not
// worth a restart. The daemon follows the pin; an unpinned install never asked it to move.
const older = (version) => Boolean(version && shipped && compareVersions(version, shipped) < 0);
const daemonStale = Boolean(daemon && (
older(daemon.pm2Version) || (pinned && daemon.nodeVersion && `v${daemon.nodeVersion}` !== running)
));
return {
node: {
version: running,
execPath: process.execPath,
source: classifyNodeSource(process.execPath, nvm?.dir),
pinned,
supportedRange: SUPPORTED_NODE_RANGE,
inSupportedRange: satisfiesVersionRequirement(running, SUPPORTED_NODE_RANGE) === true,
},
nvm: nvm ? {
dir: nvm.dir,
defaultVersion: readNvmDefault(nvm.dir),
installed: listNvmVersions(nvm.dir),
} : null,
releases: summary,
releasesError: releases ? null : 'Could not reach nodejs.org for the release list.',
pm2: {
shipped,
latest: latestPm2,
daemon,
cli,
cliBehind: older(cli),
daemonStale,
},
// The command runs that Node's global pm2, so offer it only where one exists.
startup: cli === null ? null : getStartupStatus({ nodeBinary: cliNode }),
canUpdate: blockedReason === null,
blockedReason,
job: currentJob ? { kind: currentJob.kind, startedAt: currentJob.startedAt } : null,
};
}
// One runtime job at a time; the self-update lock takes over once it launches.
let currentJob = null;
/** Refuse unless nothing is running that a restart would kill. */
async function assertIdleForRestart() {
const [{ getSystemActivity }, { describeActivityBlockers }, { checkPortosUpdatePreflight }] = await Promise.all([
import('./activeProcessing.js'),
import('../lib/systemIdle.js'),
import('./updatePreflight.js'),
]);
const processing = await getSystemActivity().catch(() => null);
if (!processing?.activity) {
throw new ServerError('Could not confirm PortOS is idle. Try again in a moment.', { status: 503, code: 'ACTIVITY_UNAVAILABLE' });
}
if (!processing.activity.idle) {
throw new ServerError(
`PortOS is busy (${describeActivityBlockers(processing.activity.blockers)}). Switching Node restarts PortOS, so it waits until that finishes.`,
{ status: 409, code: 'SYSTEM_BUSY' },
);
}
// A fork's own main is what it runs; a runtime switch is not the moment to
// demand a fork sync.
await checkPortosUpdatePreflight({ acknowledgeFork: true });
}
const childEnvFor = (nodeBinary) => withNodeBinOnPath(withoutServerSecretsEnv(process.env), nodeBinary);
function nvmCommand(nvm, args) {
// Arguments travel as positional parameters, never interpolated into the script.
return ['bash', ['-c', 'export NVM_DIR="$1"; . "$2" --no-use; shift 2; nvm "$@"', 'portos-nvm', nvm.dir, nvm.script, ...args]];
}
async function runStep(emit, step, label, command, args, { timeoutMs, env }) {
emit(step, 'running', label);
let last = '';
const run = await runStreamingCommand(command, args, (line) => {
const text = String(line).trim();
if (!text || text === last) return;
last = text;
emit(step, 'running', text.slice(0, 200));
}, { timeoutMs, env });
if (!run.success) {
throw new ServerError(`${label} failed: ${run.error || 'unknown error'}`, { status: 502, code: 'NODE_RUNTIME_STEP_FAILED' });
}
emit(step, 'done', label.replace(/…$/, ''));
}
async function installGlobalPm2(emit, nodeBinary, version) {
await runStep(emit, 'pm2-cli', `Installing pm2 ${version} for Node ${nodeVersionOf(nodeBinary)}…`,
join(dirname(nodeBinary), 'npm'), ['install', '-g', `pm2@${version}`],
{ timeoutMs: NPM_INSTALL_TIMEOUT_MS, env: childEnvFor(nodeBinary) });
}
const nodeVersionOf = (nodeBinary) => nodeBinary.match(/(v\d+\.\d+\.\d+)/)?.[1] || 'current';
/**
* Pin PortOS to `nodeBinary` and run the restart lifecycle on it. Restores the
* previous pin when the launch is refused, so a later plain restart never picks
* up a runtime whose native modules were not rebuilt.
*/
async function pinAndRestart({ io, emit, nodeBinary }) {
await assertIdleForRestart();
const previous = readPortosEnvValue(NODE_INTERPRETER_ENV_KEY);
if (nodeBinary) {
emit('node-pin', 'running', 'Pinning PortOS to the new Node…');
await upsertPortosEnvLine(NODE_INTERPRETER_ENV_KEY, nodeBinary);
emit('node-pin', 'done', `PortOS will run ${nodeBinary}`);
}
// Best effort: a stale boot script only matters at the next login, and the
// panel still shows the command when this could not fix it.
const undoStartup = nodeBinary
? await repairStartup(nodeBinary)
.then((undo) => { if (undo) emit('pm2-startup', 'done', 'Start-on-boot now uses the new Node'); return undo; })
.catch((error) => { console.warn(`⚠️ Could not update the pm2 LaunchAgent: ${error.message}`); return null; })
: null;
const { startPortosSelfUpdate } = await import('./portosSelfUpdate.js');
// A refused launch puts the pin and the boot script back together, so boot
// never starts a Node PortOS is not running on.
await startPortosSelfUpdate({ io, acknowledgeFork: true, preflightAlreadyRun: true, mode: 'refresh' }).catch(async (error) => {
if (nodeBinary) await upsertPortosEnvLine(NODE_INTERPRETER_ENV_KEY, previous ?? '');
await undoStartup?.().catch((undoError) => console.warn(`⚠️ Could not restore the pm2 LaunchAgent: ${undoError.message}`));
throw error;
});
}
function launchJob(kind, io, work, { restart = true } = {}) {
if (currentJob) {
throw new ServerError('A Node or pm2 update is already running.', { status: 409, code: 'NODE_RUNTIME_BUSY' });
}
currentJob = { kind, startedAt: new Date().toISOString() };
const emit = (step, status, message) => io?.emit('portos:update:step', { step, status, message, timestamp: Date.now() });
// Runs past the response: nvm downloads take minutes, and the restart this
// ends in outlives the request anyway. Progress and failure go out on the
// same `portos:update:*` channel the Update tab already renders.
Promise.resolve()
.then(() => work(emit))
.catch((error) => {
console.error(`❌ ${kind} failed: ${error.message}`);
io?.emit('portos:update:error', { message: error.message, step: kind });
})
.finally(() => { currentJob = null; });
// `restart: false` tells the Update tab not to wait for a restart.
return { started: true, restart };
}
/**
* Install `version` with nvm, make it nvm's default, give it the pm2 CLI
* PortOS ships, then restart PortOS on it.
*/
export async function startNodeUpdate({ version, io }) {
if (!VERSION_RE.test(version || '')) {
throw new ServerError('version must look like v26.12.1', { status: 400, code: 'VALIDATION_ERROR' });
}
const status = await getNodeRuntimeStatus();
if (!status.canUpdate) throw new ServerError(status.blockedReason, { status: 409, code: 'NODE_UPDATE_UNAVAILABLE' });
if (!status.releases?.offers.some((offer) => offer.version === version)) {
throw new ServerError(`${version} is not an available update for Node ${status.node.version}.`, { status: 400, code: 'NODE_VERSION_NOT_OFFERED' });
}
// Refuse up front so a busy install isn't left with a download it can't use yet.
await assertIdleForRestart();
const nvm = resolveNvm();
const nodeBinary = nvmNodeBinary(nvm.dir, version);
return launchJob('node-update', io, async (emit) => {
const [cmd, args] = nvmCommand(nvm, ['install', version]);
await runStep(emit, 'node-install', `Installing Node ${version} with nvm…`, cmd, args,
{ timeoutMs: NVM_INSTALL_TIMEOUT_MS, env: withoutServerSecretsEnv(process.env) });
if (!existsSync(nodeBinary)) {
throw new ServerError(`nvm finished but ${nodeBinary} is missing.`, { status: 502, code: 'NODE_RUNTIME_STEP_FAILED' });
}
const [aliasCmd, aliasArgs] = nvmCommand(nvm, ['alias', 'default', version]);
await runStep(emit, 'node-default', `Making ${version} nvm's default…`, aliasCmd, aliasArgs,
{ timeoutMs: 60_000, env: withoutServerSecretsEnv(process.env) });
if (status.pm2.shipped) await installGlobalPm2(emit, nodeBinary, status.pm2.shipped);
await pinAndRestart({ io, emit, nodeBinary });
});
}
/**
* Bring pm2 in line with the version PortOS ships: the terminal's global CLI
* under PortOS's Node, and the daemon (reloaded by the restart lifecycle) when
* it runs an older pm2 or Node. No restart when only the CLI was behind.
*/
export async function startPm2Update({ io }) {
const status = await getNodeRuntimeStatus();
const { shipped, cliBehind, daemonStale } = status.pm2;
if (!shipped) throw new ServerError('PortOS\'s own pm2 is missing. Run the PortOS update first.', { status: 409, code: 'PM2_MISSING' });
const cliNode = status.node.pinned || process.execPath;
if (!cliBehind && !daemonStale) {
throw new ServerError(`pm2 is already on ${shipped}.`, { status: 409, code: 'PM2_CURRENT' });
}
if (daemonStale) await assertIdleForRestart();
return launchJob('pm2-update', io, async (emit) => {
if (cliBehind) await installGlobalPm2(emit, cliNode, shipped);
if (daemonStale) {
await pinAndRestart({ io, emit, nodeBinary: null });
} else {
io?.emit('portos:node-runtime:changed', { reason: 'pm2-cli' });
}
}, { restart: daemonStale });
}
export const __testing = {
getStartupStatus,
resetNodeRuntimeCaches,
resolveNvm,
rewriteLaunchAgent,
summarizeNodeReleases,
};