easy-vps 0.1.0

package/dist/services/system.js

@@ -0,0 +1,286 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGES = void 0;
+exports.getMetrics = getMetrics;
+exports.detect = detect;
+exports.detectAll = detectAll;
+exports.canAdminister = canAdminister;
+exports.packageStream = packageStream;
+// Dependency detection, installation and removal on the managed VPS, over SSH.
+const packages_1 = require("./packages");
+const ssh_1 = require("./ssh");
+var packages_2 = require("./packages");
+Object.defineProperty(exports, "PACKAGES", { enumerable: true, get: function () { return packages_2.PACKAGES; } });
+function parseBytesToMb(bytes) {
+    return Math.round((bytes / 1024 / 1024) * 100) / 100;
+}
+function parseBytesToGb(bytes) {
+    return Math.round((bytes / 1024 / 1024 / 1024) * 100) / 100;
+}
+/** Collect comprehensive system metrics from the VPS. */
+async function getMetrics(remote) {
+    const metricsScript = `#!/bin/bash
+# CPU info
+cpu_model=$(grep -m1 'model name' /proc/cpuinfo 2>/dev/null | cut -d: -f2 | xargs || echo "Unknown")
+cpu_cores=$(nproc 2>/dev/null || echo 1)
+cpu_usage=$(top -bn1 2>/dev/null | grep '^%Cpu' | awk '{print 100 - $8}' || echo 0)
+
+# Memory info
+mem_info=$(free -b | grep Mem)
+mem_total=$(echo "$mem_info" | awk '{print $2}')
+mem_used=$(echo "$mem_info" | awk '{print $3}')
+mem_free=$(echo "$mem_info" | awk '{print $4}')
+mem_available=$(echo "$mem_info" | awk '{print $7}')
+
+# Swap info
+swap_info=$(free -b | grep Swap)
+swap_total=$(echo "$swap_info" | awk '{print $2}')
+swap_used=$(echo "$swap_info" | awk '{print $3}')
+swap_free=$(echo "$swap_info" | awk '{print $4}')
+
+# Disk info
+disk_info=$(df -B1 / | tail -1)
+disk_total=$(echo "$disk_info" | awk '{print $2}')
+disk_used=$(echo "$disk_info" | awk '{print $3}')
+disk_free=$(echo "$disk_info" | awk '{print $4}')
+
+# Uptime
+uptime_seconds=$(awk '{print int($1)}' /proc/uptime)
+uptime_human=$(uptime -p 2>/dev/null || echo "up $((uptime_seconds/86400)) days")
+
+# Load average
+load_avg=$(cat /proc/loadavg | awk '{print $1, $2, $3}')
+
+# Network (first non-loopback interface)
+net_rx=0
+net_tx=0
+for iface in /sys/class/net/*/statistics; do
+  iface_name=$(echo "$iface" | cut -d/ -f5)
+  if [ "$iface_name" != "lo" ] && [ -d "$iface" ]; then
+    net_rx=$(cat "$iface/rx_bytes" 2>/dev/null || echo 0)
+    net_tx=$(cat "$iface/tx_bytes" 2>/dev/null || echo 0)
+    break
+  fi
+done
+
+# Top processes by CPU
+top_procs=$(ps aux --sort=-%cpu 2>/dev/null | head -6 | tail -5 | awk '{print $11, $3, $4, $2}')
+
+echo "CPU_MODEL:$cpu_model"
+echo "CPU_CORES:$cpu_cores"
+echo "CPU_USAGE:$cpu_usage"
+echo "MEM_TOTAL:$mem_total"
+echo "MEM_USED:$mem_used"
+echo "MEM_FREE:$mem_free"
+echo "MEM_AVAILABLE:$mem_available"
+echo "SWAP_TOTAL:$swap_total"
+echo "SWAP_USED:$swap_used"
+echo "SWAP_FREE:$swap_free"
+echo "DISK_TOTAL:$disk_total"
+echo "DISK_USED:$disk_used"
+echo "DISK_FREE:$disk_free"
+echo "UPTIME_SECONDS:$uptime_seconds"
+echo "UPTIME_HUMAN:$uptime_human"
+echo "LOAD_AVG:$load_avg"
+echo "NET_RX:$net_rx"
+echo "NET_TX:$net_tx"
+echo "TOP_PROCS:$top_procs"
+`;
+    const { stdout, code } = await remote.exec((0, ssh_1.loginShell)(metricsScript), 15_000);
+    if (code !== 0) {
+        return getDefaultMetrics();
+    }
+    const lines = stdout.split('\n').filter((l) => l.includes(':'));
+    const get = (key) => {
+        const line = lines.find((l) => l.startsWith(`${key}:`));
+        return line ? line.slice(key.length + 1).trim() : '';
+    };
+    const cpuCores = parseInt(get('CPU_CORES')) || 1;
+    const cpuUsage = Math.min(100, Math.max(0, parseFloat(get('CPU_USAGE')) || 0));
+    const memTotal = parseInt(get('MEM_TOTAL')) || 0;
+    const memUsed = parseInt(get('MEM_USED')) || 0;
+    const memFree = parseInt(get('MEM_FREE')) || 0;
+    const memAvailable = parseInt(get('MEM_AVAILABLE')) || 0;
+    const memUsagePercent = memTotal > 0 ? Math.round((memUsed / memTotal) * 10000) / 100 : 0;
+    const swapTotal = parseInt(get('SWAP_TOTAL')) || 0;
+    const swapUsed = parseInt(get('SWAP_USED')) || 0;
+    const swapFree = parseInt(get('SWAP_FREE')) || 0;
+    const swapUsagePercent = swapTotal > 0 ? Math.round((swapUsed / swapTotal) * 10000) / 100 : 0;
+    const diskTotal = parseInt(get('DISK_TOTAL')) || 0;
+    const diskUsed = parseInt(get('DISK_USED')) || 0;
+    const diskFree = parseInt(get('DISK_FREE')) || 0;
+    const diskUsagePercent = diskTotal > 0 ? Math.round((diskUsed / diskTotal) * 10000) / 100 : 0;
+    const uptimeSeconds = parseInt(get('UPTIME_SECONDS')) || 0;
+    const loadParts = get('LOAD_AVG').split(/\s+/);
+    const loadOne = parseFloat(loadParts[0]) || 0;
+    const loadFive = parseFloat(loadParts[1]) || 0;
+    const loadFifteen = parseFloat(loadParts[2]) || 0;
+    const netRx = parseInt(get('NET_RX')) || 0;
+    const netTx = parseInt(get('NET_TX')) || 0;
+    const topProcsRaw = get('TOP_PROCS');
+    const topProcesses = topProcsRaw
+        ? topProcsRaw.split('\n').map((line) => {
+            const parts = line.trim().split(/\s+/);
+            return {
+                name: parts[0] || 'unknown',
+                cpu: parseFloat(parts[1]) || 0,
+                memory: parseFloat(parts[2]) || 0,
+                pid: parseInt(parts[3]) || 0,
+            };
+        })
+        : [];
+    return {
+        cpu: {
+            model: get('CPU_MODEL') || 'Unknown',
+            cores: cpuCores,
+            usagePercent: Math.round(cpuUsage * 100) / 100,
+        },
+        memory: {
+            totalMb: parseBytesToMb(memTotal),
+            usedMb: parseBytesToMb(memUsed),
+            freeMb: parseBytesToMb(memFree),
+            availableMb: parseBytesToMb(memAvailable),
+            usagePercent: Math.round(memUsagePercent * 100) / 100,
+        },
+        disk: {
+            totalGb: parseBytesToGb(diskTotal),
+            usedGb: parseBytesToGb(diskUsed),
+            freeGb: parseBytesToGb(diskFree),
+            usagePercent: Math.round(diskUsagePercent * 100) / 100,
+        },
+        swap: {
+            totalMb: parseBytesToMb(swapTotal),
+            usedMb: parseBytesToMb(swapUsed),
+            freeMb: parseBytesToMb(swapFree),
+            usagePercent: Math.round(swapUsagePercent * 100) / 100,
+        },
+        uptime: get('UPTIME_HUMAN') || 'unknown',
+        uptimeSeconds,
+        loadAverage: { one: loadOne, five: loadFive, fifteen: loadFifteen },
+        network: { rxMb: parseBytesToMb(netRx), txMb: parseBytesToMb(netTx) },
+        topProcesses,
+    };
+}
+function getDefaultMetrics() {
+    return {
+        cpu: { model: 'Unknown', cores: 0, usagePercent: 0 },
+        memory: { totalMb: 0, usedMb: 0, freeMb: 0, availableMb: 0, usagePercent: 0 },
+        disk: { totalGb: 0, usedGb: 0, freeGb: 0, usagePercent: 0 },
+        swap: { totalMb: 0, usedMb: 0, freeMb: 0, usagePercent: 0 },
+        uptime: 'unknown',
+        uptimeSeconds: 0,
+        loadAverage: { one: 0, five: 0, fifteen: 0 },
+        network: { rxMb: 0, txMb: 0 },
+        topProcesses: [],
+    };
+}
+const DETECT_TIMEOUT_MS = 10_000;
+// A non-interactive shell misses tools installed outside the system prefix.
+// System paths stay first so a distro binary wins; every installed nvm version
+// is appended, because the one holding the binary is not necessarily the
+// newest — picking just one silently misses tools under the others.
+const PATH_PRIMER = 'export PATH="/usr/local/bin:/usr/bin:/snap/bin:$PATH"; ' +
+    'for nvm_bin in "$HOME"/.nvm/versions/node/*/bin; do ' +
+    '[ -d "$nvm_bin" ] && PATH="$PATH:$nvm_bin"; done; export PATH;';
+/** Detect whether a dependency is present on the VPS. */
+async function detect(remote, name) {
+    try {
+        // nginx and certbot print their version banner on stderr
+        const { stdout, stderr, code } = await remote.exec((0, ssh_1.loginShell)(`${PATH_PRIMER} ${packages_1.PACKAGES[name].versionCommand} 2>&1`), DETECT_TIMEOUT_MS);
+        const removes = packages_1.PACKAGES[name].removes;
+        if (code !== 0)
+            return { name, installed: false, version: null, removes };
+        const version = (stdout || stderr).trim().split('\n')[0] || null;
+        return { name, installed: true, version, removes };
+    }
+    catch {
+        // A timeout or a dropped channel is reported as "not installed" rather than
+        // failing the whole status request over one wedged binary.
+        return { name, installed: false, version: null, removes: packages_1.PACKAGES[name].removes };
+    }
+}
+async function detectAll(remote) {
+    return Promise.all(packages_1.DEPENDENCY_NAMES.map((name) => detect(remote, name)));
+}
+/** True when the logged-in remote user can run privileged commands unattended. */
+async function canAdminister(remote) {
+    if (await remote.isRoot())
+        return true;
+    return (await remote.exec('sudo -n true', DETECT_TIMEOUT_MS)).code === 0;
+}
+// System locations first: pm2 installed by an nvm npm lands inside that nvm
+// prefix, which a non-interactive shell cannot see afterwards, so detection
+// would keep reporting pm2 as missing even after a successful install.
+const NPM_CANDIDATES = ['/usr/local/bin/npm', '/usr/bin/npm', '/snap/bin/npm'];
+/** Locates npm on the VPS, or returns null when Node is not installed at all. */
+async function resolveNpm(remote) {
+    const probe = [
+        ...NPM_CANDIDATES.map((candidate) => `[ -x ${(0, ssh_1.quote)(candidate)} ] && echo ${(0, ssh_1.quote)(candidate)} && exit 0`),
+        // PATH_PRIMER has already added every nvm bin, so this covers those too.
+        'command -v npm 2>/dev/null && exit 0',
+    ].join('\n');
+    const { stdout } = await remote.exec((0, ssh_1.loginShell)(`${PATH_PRIMER}\n${probe}`), DETECT_TIMEOUT_MS);
+    return stdout.trim().split('\n')[0]?.trim() || null;
+}
+/**
+ * Turns a definition's command into something runnable on the server: apt gets
+ * a refreshed index and a non-interactive frontend, and {{npm}} is replaced
+ * with a real path. npm is not reliably on a non-interactive PATH, and on a
+ * fresh VPS Node may be missing altogether — in which case installing pm2
+ * bootstraps Node from the distro first.
+ */
+async function buildScript(remote, name, action) {
+    const definition = packages_1.PACKAGES[name];
+    const command = action === 'install' ? definition.installCommand : definition.uninstallCommand;
+    if (command.includes(packages_1.NPM_PLACEHOLDER)) {
+        const npm = await resolveNpm(remote);
+        if (!npm) {
+            if (action === 'uninstall') {
+                // Nothing to uninstall through npm, but its leftovers still go.
+                return command.split(' && ').filter((part) => !part.includes(packages_1.NPM_PLACEHOLDER)).join(' && ');
+            }
+            return ('export DEBIAN_FRONTEND=noninteractive; apt-get update && ' +
+                'apt-get install -y nodejs npm && ' +
+                command.replaceAll(packages_1.NPM_PLACEHOLDER, 'npm'));
+        }
+        // Put npm's own directory first so the node binary beside it is found too.
+        return (`export PATH="$(dirname ${(0, ssh_1.quote)(npm)}):$PATH"; ` +
+            command.replaceAll(packages_1.NPM_PLACEHOLDER, (0, ssh_1.quote)(npm)));
+    }
+    // apt needs a refreshed index first; chain it so both halves stream into the
+    // same channel and the exit code reflects the real work, not the refresh.
+    return action === 'install'
+        ? `export DEBIAN_FRONTEND=noninteractive; apt-get update && ${command}`
+        : `export DEBIAN_FRONTEND=noninteractive; ${command}`;
+}
+/**
+ * Installs or removes a dependency on the VPS, streaming stdout/stderr line by
+ * line. Returns a function that cancels the run in progress.
+ */
+function packageStream(remote, name, action, handlers) {
+    if (!(name in packages_1.PACKAGES)) {
+        handlers.onError(`Unknown dependency "${name}"`);
+        return () => undefined;
+    }
+    let cancel = () => undefined;
+    let cancelled = false;
+    void (async () => {
+        if (!(await canAdminister(remote))) {
+            handlers.onError(`"${remote.username}" cannot run privileged commands on ${remote.host}. ` +
+                'Log in as root, or enable passwordless sudo.');
+            return;
+        }
+        const script = await buildScript(remote, name, action);
+        if (cancelled)
+            return;
+        handlers.onOutput(`$ ${script}`);
+        cancel = remote.execStream(await remote.privileged((0, ssh_1.loginShell)(script)), handlers);
+    })().catch((error) => {
+        if (!cancelled)
+            handlers.onError(error.message);
+    });
+    return () => {
+        cancelled = true;
+        cancel();
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "easy-vps",
+  "version": "0.1.0",
+  "description": "Install dependencies, point domains, deploy apps and run Postgres on a VPS from one UI",
+  "keywords": [
+    "vps",
+    "nginx",
+    "pm2",
+    "docker",
+    "certbot",
+    "postgres",
+    "deploy"
+  ],
+  "license": "MIT",
+  "bin": {
+    "easy-vps": "bin/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "client",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "npm run build:server && npm run build:client",
+    "build:dev": "npm run build:server && npm run build:client",
+    "build:server": "tsc -p tsconfig.json",
+    "build:client": "npm --prefix client-ui run build",
+    "dev": "node scripts/dev.js",
+    "dev:server": "tsc -p tsconfig.json --watch",
+    "dev:client": "npm --prefix client-ui run dev",
+    "start": "node bin/cli.js",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1118.0",
+    "express": "^4.21.2",
+    "node-cron": "^4.6.0",
+    "ssh2": "^1.17.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^24.13.3",
+    "@types/node-cron": "^3.0.11",
+    "@types/ssh2": "^1.15.5",
+    "typescript": "~5.9.3"
+  }
+}

package/scripts/dev.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+'use strict'
+
+// One command for local development: compiles the server, runs it on 41556,
+// and starts the Vite dev server on 41557 which proxies /api back to it.
+//
+// Running Vite alone leaves the proxy with nothing to talk to, which shows up
+// as `ECONNREFUSED 127.0.0.1:41556` in the Vite log.
+
+const { spawn, spawnSync } = require('node:child_process')
+const path = require('node:path')
+
+const ROOT = path.resolve(__dirname, '..')
+const PANEL_PORT = Number(process.env.EASY_VPS_PORT) || 41556
+const UI_PORT = Number(process.env.EASY_VPS_UI_PORT) || PANEL_PORT + 1
+const ESC = String.fromCharCode(27)
+const color = process.stdout.isTTY && !process.env.NO_COLOR
+
+const paint = (code, text) => (color ? `${ESC}[${code}m${text}${ESC}[0m` : text)
+const LABEL = {
+  tsc: paint(35, 'tsc  '),
+  api: paint(36, 'api  '),
+  ui: paint(32, 'ui   '),
+}
+
+const children = []
+
+/** Prefix every line of a child's output so the three streams stay readable. */
+function prefix(label, stream) {
+  let buffer = ''
+  stream.on('data', (chunk) => {
+    buffer += chunk.toString()
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+    for (const line of lines) {
+      if (line.trim()) console.log(`${label} ${paint(2, '|')} ${line}`)
+    }
+  })
+}
+
+function start(label, command, args, options = {}) {
+  const child = spawn(command, args, { cwd: ROOT, ...options })
+  prefix(label, child.stdout)
+  prefix(label, child.stderr)
+  child.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      console.log(`${label} ${paint(2, '|')} exited with code ${code}`)
+    }
+  })
+  children.push(child)
+  return child
+}
+
+function shutdown() {
+  for (const child of children) {
+    child.kill('SIGTERM')
+  }
+  process.exit(0)
+}
+
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)
+
+// A first compile must finish before the server can boot.
+console.log(`${LABEL.tsc} ${paint(2, '|')} building server…`)
+const build = spawnSync('npx', ['tsc', '-p', 'tsconfig.json'], { cwd: ROOT, encoding: 'utf8' })
+
+if (build.status !== 0) {
+  console.error(build.stdout || build.stderr)
+  console.error('server build failed — fix the errors above and rerun')
+  process.exit(1)
+}
+
+// Recompile on change; `node --watch` restarts the server when dist/ updates.
+start(LABEL.tsc, 'npx', ['tsc', '-p', 'tsconfig.json', '--watch', '--preserveWatchOutput'])
+const env = {
+  ...process.env,
+  EASY_VPS_HOST: '127.0.0.1',
+  EASY_VPS_PORT: String(PANEL_PORT),
+  EASY_VPS_UI_PORT: String(UI_PORT),
+}
+
+start(LABEL.api, process.execPath, ['--watch', 'bin/cli.js'], { env })
+start(LABEL.ui, 'npm', ['--prefix', 'client-ui', 'run', 'dev'], { env })
+
+console.log(
+  `${LABEL.ui} ${paint(2, '|')} open http://localhost:${UI_PORT} — the UI proxies /api to ${PANEL_PORT}`,
+)

package/scripts/postinstall.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict'
+
+// Runs after `npm i -g easy-vps`: verifies the payload, prepares the UI,
+// opens the port and starts the panel as a background service.
+//
+// Never throws — a failing postinstall aborts the whole npm install, so every
+// step degrades to a warning and the user is told how to finish by hand.
+
+const { execFileSync } = require('node:child_process')
+const { existsSync } = require('node:fs')
+const path = require('node:path')
+
+const ui = require('./ui')
+
+const ROOT = path.resolve(__dirname, '..')
+const PORT = Number(process.env.EASY_VPS_PORT) || 41556
+const HOST = process.env.EASY_VPS_HOST || '0.0.0.0'
+
+/** Skip the whole hook for local/dev installs and opt-outs. */
+function shouldSkip() {
+  if (process.env.EASY_VPS_NO_AUTOSTART) return 'EASY_VPS_NO_AUTOSTART is set'
+  if (process.env.CI) return 'running in CI'
+  // npm sets this for `npm i -g`; a local dependency install must not start a server
+  if (process.env.npm_config_global !== 'true') return 'not a global install'
+  return null
+}
+
+function verifyPayload() {
+  const missing = ['dist/index.js', 'bin/cli.js'].filter((f) => !existsSync(path.join(ROOT, f)))
+  if (missing.length) throw new Error(`missing ${missing.join(', ')}`)
+}
+
+/**
+ * The UI ships prebuilt in the tarball. It is only absent when running from a
+ * source checkout, where client-ui/ is present and can be built.
+ */
+function prepareUI() {
+  if (existsSync(path.join(ROOT, 'client', 'index.html'))) return 'prebuilt'
+  if (!existsSync(path.join(ROOT, 'client-ui', 'package.json'))) throw new Error('no UI payload')
+
+  execFileSync('npm', ['--prefix', path.join(ROOT, 'client-ui'), 'run', 'build'], {
+    stdio: 'ignore',
+  })
+  return 'built'
+}
+
+async function main() {
+  const skip = shouldSkip()
+  if (skip) return
+
+  let daemon
+  ui.blank()
+
+  ui.step('installing easy vps')
+  try {
+    verifyPayload()
+    daemon = require(path.join(ROOT, 'dist', 'services', 'daemon.js'))
+    ui.done('easy vps installed')
+  } catch (error) {
+    ui.warn(`easy vps installed, but the payload looks incomplete (${error.message})`)
+    return
+  }
+
+  ui.step('compiling user interface')
+  try {
+    prepareUI()
+    ui.done('user interface ready')
+  } catch (error) {
+    ui.warn(`user interface unavailable (${error.message})`)
+  }
+
+  ui.step('enabling port')
+  try {
+    const opened = await daemon.openFirewall(PORT)
+    if (opened) ui.done(`port ${PORT} enabled`)
+    else if (!daemon.isRoot()) ui.done(`port ${PORT} ready ${ui.dim('(firewall not changed: not root)')}`)
+    else ui.done(`port ${PORT} ready ${ui.dim('(no active ufw firewall to update)')}`)
+  } catch (error) {
+    ui.warn(`could not enable port ${PORT} (${error.message})`)
+  }
+
+  ui.step('starting service')
+  let running = false
+  try {
+    const mode = await daemon.start({ port: PORT, host: HOST })
+    const state = await daemon.status()
+    running = state.running
+    if (running) {
+      ui.done(
+        mode === 'systemd'
+          ? 'service started (systemd, restarts on reboot)'
+          : `service started ${ui.dim('(background process)')}`,
+      )
+    } else {
+      ui.warn(`service did not start (${state.detail})`)
+    }
+  } catch (error) {
+    ui.warn(`service did not start (${error.message})`)
+  }
+
+  ui.blank()
+
+  if (!running) {
+    ui.warn('Setup finished with warnings. Start it by hand with: easy-vps start')
+    ui.blank()
+    return
+  }
+
+  ui.done(ui.bold('All process are completed'))
+  const hosts = daemon.addresses()
+  const shown = hosts.length ? hosts : ['[vps-ip]']
+  for (const address of shown) {
+    ui.line(`  in your browser visit ${ui.bold(`http://${address}:${PORT}`)} to see the graphical interface`)
+  }
+  ui.blank()
+  ui.line(ui.dim(`  easy-vps status | easy-vps stop | easy-vps logs`))
+  ui.blank()
+}
+
+main()
+  .catch(() => undefined)
+  .finally(() => ui.close())

package/scripts/preuninstall.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict'
+
+// Stops the panel and removes its systemd unit before the package is deleted.
+const path = require('node:path')
+const ui = require('./ui')
+
+async function main() {
+  if (process.env.npm_config_global !== 'true') return
+  try {
+    const daemon = require(path.resolve(__dirname, '..', 'dist', 'services', 'daemon.js'))
+    await daemon.uninstall()
+    ui.done('easy vps service stopped and removed')
+  } catch {
+    // nothing installed, or no permission — leave the uninstall itself alone
+  }
+}
+
+main()
+  .catch(() => undefined)
+  .finally(() => ui.close())

package/scripts/try-install.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Rehearse `npm i -g easy-vps` locally, without touching the real global prefix.
+#
+#   ./scripts/try-install.sh          install into a sandbox prefix and check it
+#   ./scripts/try-install.sh clean    remove the sandbox and stop the panel
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SANDBOX="${TMPDIR:-/tmp}/easy-vps-sandbox"
+PORT="${EASY_VPS_PORT:-41556}"
+
+cleanup() {
+  if [ -x "$SANDBOX/bin/easy-vps" ]; then
+    "$SANDBOX/bin/easy-vps" uninstall >/dev/null 2>&1 || true
+  fi
+  rm -rf "$SANDBOX"
+  rm -f "$ROOT"/easy-vps-*.tgz
+  echo "sandbox removed"
+}
+
+if [ "${1:-}" = "clean" ]; then
+  cleanup
+  exit 0
+fi
+
+trap 'echo "FAILED"; exit 1' ERR
+
+echo "==> building"
+npm --prefix "$ROOT" run build >/dev/null
+
+echo "==> packing"
+rm -f "$ROOT"/easy-vps-*.tgz
+TARBALL="$ROOT/$(cd "$ROOT" && npm pack --silent)"
+
+echo "==> installing globally into $SANDBOX"
+rm -rf "$SANDBOX"
+mkdir -p "$SANDBOX"
+export NPM_CONFIG_PREFIX="$SANDBOX"
+# a pty makes the postinstall banner visible, exactly as a real terminal would
+if command -v script >/dev/null 2>&1; then
+  script -qec "npm i -g '$TARBALL'" /dev/null
+else
+  npm i -g "$TARBALL"
+fi
+
+export PATH="$SANDBOX/bin:$PATH"
+
+echo
+echo "==> checking"
+for _ in $(seq 1 30); do
+  code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:$PORT/api/health" || true)
+  [ "$code" = "200" ] && break
+  sleep 0.5
+done
+
+[ "$code" = "200" ] || { echo "panel did not answer on port $PORT"; exit 1; }
+
+echo "  health   $(curl -s "http://localhost:$PORT/api/health")"
+echo "  ui       HTTP $(curl -s -o /dev/null -w '%{http_code}' "http://localhost:$PORT/")"
+echo "  deps     $(curl -s "http://localhost:$PORT/api/system/status")"
+easy-vps status
+
+echo
+echo "PASS — open http://localhost:$PORT/"
+echo "When done:  $0 clean"