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
fix: check the target Node requirement before stopping apps for an update (#10947)
Adam Eivya7c2e73ad4ba
diff --git a/docs/SETUP.md b/docs/SETUP.mdindex 3d6cd83878..2f2a8f7fe2 100644--- a/docs/SETUP.md+++ b/docs/SETUP.md@@ -102,6 +102,8 @@ Certificate provisioning and the PortOS restart are one-click actions in the UI`update.sh`, `update.ps1`, and the in-app updater retry the safe certificate provisioning step on every update, report the current network prerequisite in update progress, and print the full walkthrough afterward. An update does not fail merely because Tailscale is absent or an account toggle still needs you.+Updates check the pulled version's Node.js requirement (the same `scripts/checkNodeVersion.js` gate that `npm start` uses) before stopping any app or installing dependencies. If your Node.js is too old, the update stops with the required range and leaves PortOS running; the checkout is already on the new revision, so upgrade Node.js (for example `nvm install` using `.nvmrc`) and re-run the update.+Useful checks:```bashdiff --git a/scripts/update-headless-recovery.test.js b/scripts/update-headless-recovery.test.jsindex e93af39e42..6f0d5a171e 100644--- a/scripts/update-headless-recovery.test.js+++ b/scripts/update-headless-recovery.test.js@@ -36,7 +36,7 @@ const STUB_SCRIPTS = [*/async function makeSandbox({origin = true, failAfterDelete = true, npmShim = 'ok',- forceClean = false, pm2OnPath = false, healthy = true, stallDelete = false+ forceClean = false, pm2OnPath = false, healthy = true, stallDelete = false, nodeVersion = null} = {}) {const { scratch, repo } = await makeGitSandbox({ origin, prefix: 'portos-update-guard-' });const bin = join(scratch, 'bin');@@ -73,6 +73,19 @@ if (${stallDelete} && args.startsWith('delete')) {`);+ // The REAL runtime gate (the pulled target's own copy), so the preflight+ // exercises the shared requirement rather than a stub with a copied floor.+ mkdirSync(join(repo, 'scripts', 'lib'), { recursive: true });+ copyFileSync(join(REPO_ROOT, 'scripts', 'checkNodeVersion.js'), join(repo, 'scripts', 'checkNodeVersion.js'));+ copyFileSync(join(REPO_ROOT, 'scripts', 'lib', 'directInvocation.js'), join(repo, 'scripts', 'lib', 'directInvocation.js'));+ // Make the interpreter report an older runtime to that gate (and only to it).+ let nodeOptions = '';+ if (nodeVersion) {+ const preload = join(scratch, 'fake-node-version.mjs');+ writeFileSync(preload, `Object.defineProperty(process.versions, 'node', { value: ${JSON.stringify(nodeVersion)} });\n`);+ nodeOptions = `--import=${preload}`;+ }+writeFileSync(join(repo, 'scripts', 'SLASHDO_VERSION'), '0.0.0\n');writeFileSync(join(repo, 'scripts', 'trusted-rebuilds.js'), `process.exit(${failAfterDelete ? 1 : 0});\n`);for (const stub of STUB_SCRIPTS) {@@ -116,7 +129,7 @@ if (${stallDelete} && args.startsWith('delete')) {execFileSync('git', ['add', '.'], { cwd: repo });execFileSync('git', ['commit', '-m', 'fixture'], { cwd: repo, stdio: 'ignore' });- return { scratch, repo, bin, calls, forceClean, releaseFile };+ return { scratch, repo, bin, calls, forceClean, releaseFile, nodeOptions };}// The three runs share no state, so they go out concurrently rather than@@ -125,6 +138,7 @@ function runUpdate(sandbox, { onStart } = {}) {return new Promise((resolve) => {const env = { ...process.env, PATH: `${sandbox.bin}:${process.env.PATH}` };if (sandbox.forceClean) env.PORTOS_FORCE_CLEAN_WORKSPACES = '.';+ if (sandbox.nodeOptions) env.NODE_OPTIONS = sandbox.nodeOptions;const child = spawn('bash', [join(sandbox.repo, 'update.sh')], { cwd: sandbox.repo, env });let stdout = '';child.stdout.on('data', (d) => { stdout += d; });@@ -161,6 +175,8 @@ describe.skipIf(process.platform === 'win32' || SKIP_HEAVY_INTEGRATION)('update.clean: { failAfterDelete: false },preDelete: { origin: false },unhealthy: { healthy: false },+ // A target whose Node requirement the installed runtime no longer meets.+ oldNode: { nodeVersion: '22.12.0' },// The failure the guard's own comment names: both npm installs fail, and// safe_install wiped root node_modules — pm2 included — on the way.pm2Wiped: { npmShim: 'fail', forceClean: true, pm2OnPath: true }@@ -242,6 +258,22 @@ describe.skipIf(process.platform === 'win32' || SKIP_HEAVY_INTEGRATION)('update.}}, 120000);+ it('refuses an unsupported Node runtime before stopping apps or installing', () => {+ const { status, stdout } = results.oldNode;+ expect(status).toBe(1);+ expect(stdout).toContain('STEP:runtime-preflight:failed:');+ expect(stdout).toContain('Node.js ^22.22.2');+ expect(stdout).not.toContain('STEP:pm2-stop:');+ expect(stdout).not.toContain('STEP:npm-install:');+ expect(pm2Calls(sandboxes.oldNode)).toEqual([]);+ });++ it('passes the runtime preflight on a supported runtime without changing the flow', () => {+ expect(results.clean.stdout).toContain('STEP:runtime-preflight:done:');+ expect(results.clean.stdout.indexOf('STEP:runtime-preflight:done:'))+ .toBeLessThan(results.clean.stdout.indexOf('STEP:pm2-stop:running:'));+ });+it('does not touch PM2 when the update aborts before the delete', () => {expect(results.preDelete.status).not.toBe(0);expect(pm2Calls(sandboxes.preDelete)).toEqual([]);@@ -294,6 +326,14 @@ describe('update.ps1 headless-install guard', () => {expect(returns.every(line => /^return\s+@\(/.test(line))).toBe(true);});+ it('runs the target Node gate before the PM2 delete and any install', () => {+ const gate = lineOf('node scripts/checkNodeVersion.js');+ expect(gate).toBeGreaterThan(-1);+ expect(gate).toBeLessThan(lineOf('pm2 delete ecosystem.config.cjs --silent'));+ expect(gate).toBeLessThan(lineOf('Safe-Install -Dir "."'));+ expect(ps1.slice(gate, gate + 8).join('\n')).toContain('Stop-UpdateScript 1');+ });+it('arms the latch before the delete, not after', () => {const armed = lineOf('$script:Pm2AppsDown = $true');const deleted = lineOf('pm2 delete ecosystem.config.cjs --silent');diff --git a/update.ps1 b/update.ps1index 5c77cc15ae..39c850e2d7 100644--- a/update.ps1+++ b/update.ps1@@ -375,6 +375,21 @@ if ($LASTEXITCODE -ne 0) { Stop-UpdateScript $LASTEXITCODE }Step "submodules" "done" "Submodules updated"Write-SafeHost ""+# Runtime preflight (see update.sh): run the pulled target's own Node gate before+# any PM2 delete or dependency change. The checkout stays on the pulled revision.+Step "runtime-preflight" "running" "Checking Node.js against the updated requirements..."+if (Test-Path "scripts/checkNodeVersion.js") {+ $nodeGateOutput = (node scripts/checkNodeVersion.js 2>&1 | Out-String).Trim()+ if ($LASTEXITCODE -ne 0) {+ Write-SafeHost $nodeGateOutput+ Write-SafeHost "❌ Update stopped before changing running apps: upgrade Node.js, then re-run the update. The checkout is already on the pulled revision." -ForegroundColor Red+ Step "runtime-preflight" "failed" "Unsupported Node.js runtime; PortOS apps were left running"+ Stop-UpdateScript 1+ }+}+Step "runtime-preflight" "done" "Node.js runtime supported"+Write-SafeHost ""+# Remove ONLY PortOS's apps from the shared PM2 daemon — never `pm2 kill`, which# tears down the daemon and stops EVERY other project's apps on this machine.# The daemon itself is left alone here; whether it also needs an in-place reloaddiff --git a/update.sh b/update.shindex 3d689b186d..ccb99727d3 100755--- a/update.sh+++ b/update.sh@@ -217,6 +217,21 @@ run git submodule update --init --recursivestep "submodules" "done" "Submodules updated"log ""+# Runtime preflight: the pulled target owns its Node support range (it may have+# just been raised), and npm's engines field only warns. Ask the target's own+# gate — the same one `npm start`/`npm run setup` run — BEFORE deleting any app+# or touching dependencies, so an unsupported runtime refuses while PortOS is+# still up instead of mid-downtime. The checkout stays on the pulled revision.+step "runtime-preflight" "running" "Checking Node.js against the updated requirements..."+if [ -f scripts/checkNodeVersion.js ] && ! node_gate_output=$(node scripts/checkNodeVersion.js 2>&1); then+ log "$node_gate_output"+ log "❌ Update stopped before changing running apps: upgrade Node.js, then re-run the update. The checkout is already on the pulled revision."+ step "runtime-preflight" "failed" "Unsupported Node.js runtime; PortOS apps were left running"+ exit 1+fi+step "runtime-preflight" "done" "Node.js runtime supported"+log ""+# Headless-install guard. From the `pm2-stop` step below until the closing# `pm2 start` succeeds, PortOS's PM2 entries are DELETED — the install has no# server. Every step in between (npm install, setup-db, migrations, the client