mop-agent 0.1.0

package/installer/bootstrap.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * npm bootstrap for the canonical command: `npx mop-agent`.
+ *
+ * The npx cache is temporary, so this file copies the packaged application to
+ * a durable directory before launching the real installer. It starts as the
+ * normal user and uses sudo only to create/fix ownership of the system app dir.
+ */
+import { spawnSync } from "node:child_process";
+import {
+  accessSync,
+  constants,
+  cpSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { platform } from "node:os";
+import { dirname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const manifest = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, "package.json"), "utf8"));
+const VERSION = manifest.version;
+const DEFAULT_DIR = "/opt/mop-agent";
+const APP_DIR = resolve(process.env.MOP_AGENT_DIR || DEFAULT_DIR);
+const argv = process.argv.slice(2);
+const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+
+function fail(message) {
+  console.error(`\n✗ ${message}\n`);
+  process.exit(1);
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { stdio: "inherit", ...options });
+  if (result.error) fail(`${command} failed: ${result.error.message}`);
+  if (result.status !== 0) fail(`${command} exited with code ${result.status ?? 1}.`);
+}
+
+function help() {
+  console.log(`
+MOP-AGENT ${VERSION}
+
+Usage:
+  npx mop-agent              Open the installer menu
+  npx mop-agent install      Install nginx and Certbot
+  npx mop-agent setup        Configure domain, HTTPS, app and systemd
+  npx mop-agent status       Show service health and file locations
+  npx mop-agent update       Apply the npm version selected by npx
+  npx mop-agent uninstall    Remove service and nginx config
+
+Environment:
+  MOP_AGENT_DIR              Durable app directory (default: ${DEFAULT_DIR})
+
+Run this command as your normal user. MOP-AGENT asks for sudo only when an OS
+operation requires it. Native Windows/macOS production installation is not yet
+supported; use WSL2 Ubuntu on Windows or a Linux host.
+`);
+}
+
+function assertPlatform() {
+  if (platform() === "linux") return;
+  if (platform() === "win32") {
+    fail("Native Windows installation is not supported. Run `npx mop-agent` inside WSL2 Ubuntu.");
+  }
+  if (platform() === "darwin") {
+    fail("macOS production installation is not supported yet. Use development mode or a Linux host.");
+  }
+  fail(`Unsupported platform: ${platform()}.`);
+}
+
+function assertSafeDestination() {
+  const forbidden = new Set(["/", "/bin", "/boot", "/dev", "/etc", "/home", "/lib", "/proc", "/root", "/run", "/sbin", "/sys", "/usr", "/var"]);
+  if (forbidden.has(APP_DIR)) fail(`Refusing unsafe MOP_AGENT_DIR: ${APP_DIR}`);
+}
+
+function writable(path) {
+  try {
+    accessSync(path, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ensureDestination() {
+  if (existsSync(APP_DIR) && writable(APP_DIR)) return;
+  if (isRoot) fail("Do not run `npx mop-agent` with sudo/root. Run it as your normal user.");
+  const uid = String(process.getuid());
+  const gid = String(process.getgid());
+  console.log(`\n▸ Preparing ${APP_DIR} (sudo is required once for this system directory)`);
+  run("sudo", ["install", "-d", "-o", uid, "-g", gid, APP_DIR]);
+  if (!writable(APP_DIR)) {
+    run("sudo", ["chown", "-R", `${uid}:${gid}`, APP_DIR]);
+  }
+}
+
+function shouldCopy(source) {
+  const rel = relative(PACKAGE_ROOT, source);
+  if (!rel) return true;
+  const first = rel.split(sep)[0];
+  if (["node_modules", ".git", ".next", "data"].includes(first)) return false;
+  if (rel === "apps/web/.env") return false;
+  return true;
+}
+
+function deployPackage() {
+  const marker = resolve(APP_DIR, ".mop-agent-version");
+  const current = existsSync(marker) ? readFileSync(marker, "utf8").trim() : "";
+  const ready = current === VERSION && existsSync(resolve(APP_DIR, "installer/mop-agent.mjs"));
+  if (ready) {
+    console.log(`✓ MOP-AGENT ${VERSION} already staged at ${APP_DIR}`);
+    return;
+  }
+
+  console.log(`\n▸ Staging MOP-AGENT ${VERSION} → ${APP_DIR}`);
+  cpSync(PACKAGE_ROOT, APP_DIR, {
+    recursive: true,
+    force: true,
+    filter: shouldCopy,
+  });
+
+  console.log("▸ Installing application dependencies");
+  const lock = existsSync(resolve(APP_DIR, "npm-shrinkwrap.json"));
+  run("npm", [lock ? "ci" : "install", "--include=dev", "--no-audit", "--no-fund"], { cwd: APP_DIR });
+  writeFileSync(marker, `${VERSION}\n`, { mode: 0o644 });
+  console.log(`✓ MOP-AGENT ${VERSION} staged\n`);
+}
+
+function selfTest() {
+  const required = [
+    "installer/mop-agent.mjs",
+    "installer/lib.mjs",
+    "apps/web/package.json",
+    "apps/web/server.ts",
+    "packages/link-protocol/package.json",
+    "packages/flow-connector/package.json",
+  ];
+  const missing = required.filter((file) => !existsSync(resolve(PACKAGE_ROOT, file)));
+  if (missing.length) fail(`Package is missing runtime files: ${missing.join(", ")}`);
+  console.log(`bootstrap self-test PASS (${VERSION})`);
+}
+
+if (argv.includes("--help") || argv.includes("-h")) {
+  help();
+} else if (argv.includes("--version") || argv.includes("-v")) {
+  console.log(VERSION);
+} else if (argv.includes("--self-test")) {
+  selfTest();
+} else {
+  assertPlatform();
+  assertSafeDestination();
+  if (isRoot) fail("Do not run `npx mop-agent` with sudo/root. Run it as your normal user.");
+  ensureDestination();
+  deployPackage();
+  run(process.execPath, [resolve(APP_DIR, "installer/mop-agent.mjs"), ...argv], {
+    cwd: APP_DIR,
+    env: { ...process.env, MOP_AGENT_MANAGED_BY_NPX: "1" },
+  });
+}

package/installer/lib.mjs

@@ -0,0 +1,196 @@
+/**
+ * MOP-AGENT installer library — OS detection, config generators, and step plans.
+ * Pure / side-effect-free where possible so it's unit-testable. Execution lives
+ * in mop-agent.mjs (guarded by --dry-run / root check).
+ */
+import { readFileSync } from "node:fs";
+import { platform } from "node:os";
+
+export const colors = {
+  reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+  green: "\x1b[32m", yellow: "\x1b[33m", red: "\x1b[31m", cyan: "\x1b[36m", gray: "\x1b[90m",
+};
+export const c = (name, v) => `${colors[name] ?? ""}${v}${colors.reset}`;
+
+/** Detect platform + distro family + package manager commands. */
+export function detectOS() {
+  const plat = platform();
+  if (plat !== "linux") {
+    return { platform: plat, distro: plat, family: "unsupported", pkg: null };
+  }
+  let id = "", idLike = "", pretty = "Linux";
+  try {
+    const os = readFileSync("/etc/os-release", "utf8");
+    id = (os.match(/^ID=(.*)$/m)?.[1] ?? "").replace(/"/g, "");
+    idLike = (os.match(/^ID_LIKE=(.*)$/m)?.[1] ?? "").replace(/"/g, "");
+    pretty = (os.match(/^PRETTY_NAME=(.*)$/m)?.[1] ?? "Linux").replace(/"/g, "");
+  } catch {
+    /* no /etc/os-release */
+  }
+  const hay = `${id} ${idLike}`.toLowerCase();
+  let family = "unknown", pkg = null;
+  if (/debian|ubuntu|kali|mint/.test(hay)) {
+    family = "debian";
+    pkg = { update: "apt-get update -y", install: "DEBIAN_FRONTEND=noninteractive apt-get install -y",
+      pkgs: { nginx: "nginx", certbot: "certbot python3-certbot-nginx" } };
+  } else if (/rhel|fedora|centos|rocky|alma/.test(hay)) {
+    family = "rhel";
+    pkg = { update: "dnf -y makecache", install: "dnf install -y",
+      pkgs: { nginx: "nginx", certbot: "certbot python3-certbot-nginx" } };
+  } else if (/arch|manjaro/.test(hay)) {
+    family = "arch";
+    pkg = { update: "pacman -Sy --noconfirm", install: "pacman -S --noconfirm",
+      pkgs: { nginx: "nginx", certbot: "certbot certbot-nginx" } };
+  } else if (/alpine/.test(hay)) {
+    family = "alpine";
+    pkg = { update: "apk update", install: "apk add",
+      pkgs: { nginx: "nginx", certbot: "certbot certbot-nginx" } };
+  }
+  return { platform: plat, distro: id || "linux", pretty, family, pkg };
+}
+
+/** nginx reverse-proxy vhost — includes WebSocket upgrade for /link + streaming chat. */
+export function renderNginxVhost({ domain, port }) {
+  return `# Managed by MOP-AGENT installer
+server {
+    listen 80;
+    listen [::]:80;
+    server_name ${domain};
+
+    location / {
+        proxy_pass http://127.0.0.1:${port};
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 86400;
+    }
+}
+`;
+}
+
+/** nginx TLS vhost used after Certbot's standalone fallback. */
+export function renderNginxTlsVhost({ domain, port }) {
+  return `# Managed by MOP-AGENT installer
+server {
+    listen 80;
+    listen [::]:80;
+    server_name ${domain};
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name ${domain};
+
+    ssl_certificate /etc/letsencrypt/live/${domain}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/${domain}/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:${port};
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 86400;
+    }
+}
+`;
+}
+
+/** systemd unit — auto-start on boot + restart on crash. */
+export function renderSystemdUnit({ appDir, port, user = "root", npm = "npm" }) {
+  return `# Managed by MOP-AGENT installer
+[Unit]
+Description=MOP-AGENT (self-hostable AI brain)
+After=network.target
+
+[Service]
+Type=simple
+User=${user}
+WorkingDirectory=${appDir}/apps/web
+Environment=NODE_ENV=production
+Environment=PORT=${port}
+EnvironmentFile=${appDir}/apps/web/.env
+ExecStart=${npm} run start
+Restart=always
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+/** Planned shell steps to install system deps (returned, not executed). */
+export function planInstallDeps(os) {
+  if (!os.pkg) return [];
+  const p = os.pkg;
+  const steps = [{ label: "Refresh package index", cmd: p.update }];
+  steps.push({ label: "Install nginx", cmd: `${p.install} ${p.pkgs.nginx}` });
+  steps.push({ label: "Enable + start nginx", cmd: "systemctl enable --now nginx" });
+  steps.push({ label: "Install certbot", cmd: `${p.install} ${p.pkgs.certbot}` });
+  return steps;
+}
+
+/** SSL via certbot with a fallback when :80 is busy. Returns ordered attempts. */
+export function planSsl({ domain, email }) {
+  const base = `certbot --nginx -d ${domain} --non-interactive --agree-tos -m ${email} --redirect`;
+  return {
+    primary: { label: "Obtain TLS cert (certbot --nginx)", cmd: base },
+    // fallback: free :80, use standalone, then reload nginx
+    fallback: [
+      { label: "Stop nginx (free port 80)", cmd: "systemctl stop nginx" },
+      { label: "Obtain cert (standalone)", cmd: `certbot certonly --standalone -d ${domain} --non-interactive --agree-tos -m ${email}` },
+      { label: "Start nginx", cmd: "systemctl start nginx" },
+    ],
+  };
+}
+
+/** What is listening on :80 (for the fallback scan). */
+export const PORT80_SCAN = "ss -ltnp 'sport = :80' 2>/dev/null || lsof -i :80 2>/dev/null || true";
+
+export function isValidDomain(value) {
+  return /^(?=.{1,253}$)(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,63}$/.test(value);
+}
+
+export function isValidEmail(value) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) && !/["'`;|&<>$()]/.test(value);
+}
+
+export function isValidPort(value) {
+  const port = Number(value);
+  return /^\d+$/.test(String(value)) && Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+
+/** nginx config location differs by distro (debian uses sites-available/enabled). */
+export function nginxPaths(family) {
+  if (family === "debian") {
+    return { conf: "/etc/nginx/sites-available/mop-agent.conf", enabled: "/etc/nginx/sites-enabled/mop-agent.conf" };
+  }
+  // rhel / arch / alpine: drop-in conf.d is auto-included by the main nginx.conf
+  return { conf: "/etc/nginx/conf.d/mop-agent.conf", enabled: null };
+}
+
+/** Canonical install locations — shown in the TUI and the README. */
+export function installPaths(appDir, family) {
+  const ng = nginxPaths(family);
+  return {
+    "app code": appDir,
+    "env file": `${appDir}/apps/web/.env`,
+    "brain + db": `${appDir}/data  (SQLite + sqlite-vec; MOP_AGENT_DATA_DIR)`,
+    "nginx vhost": ng.conf,
+    "nginx enabled": ng.enabled ?? "(auto-included via conf.d)",
+    "systemd unit": "/etc/systemd/system/mop-agent.service",
+    "tls certs": "/etc/letsencrypt/live/<domain>/  (certbot-managed)",
+    logs: "journalctl -u mop-agent -f",
+  };
+}

package/installer/mop-agent.mjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * MOP-AGENT installer / operator (TUI). Self-host with one command.
+ *
+ *   npx mop-agent            # interactive TUI
+ *   npx mop-agent install    # install system deps (nginx/certbot)
+ *   npx mop-agent setup      # domain / SQLite / ssl / systemd
+ *   npx mop-agent update     # migrate + build + restart staged npm version
+ *   npx mop-agent status     # health
+ *   npx mop-agent uninstall  # remove service + nginx vhost (keeps data unless --purge)
+ *
+ * Run as a normal user. Privileged OS operations request sudo individually.
+ */
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { chmodSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  c, detectOS, renderNginxVhost, renderNginxTlsVhost, renderSystemdUnit,
+  planInstallDeps, planSsl, PORT80_SCAN, isValidDomain, isValidEmail, isValidPort,
+  nginxPaths, installPaths,
+} from "./lib.mjs";
+
+const APP_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith("--")) { out._.push(a); continue; }
+    const [k, inline] = a.slice(2).split("=", 2);
+    if (inline !== undefined) out[k] = inline;
+    else if (!argv[i + 1] || argv[i + 1].startsWith("--")) out[k] = true;
+    else { out[k] = argv[++i]; }
+  }
+  return out;
+}
+const args = parseArgs(process.argv.slice(2));
+const DRY = !!args["dry-run"];
+const managedByNpx = process.env.MOP_AGENT_MANAGED_BY_NPX === "1";
+
+function banner() {
+  console.log(c("cyan", c("bold", "\n  🧠 MOP-AGENT installer")));
+  const os = detectOS();
+  console.log(c("gray", `  ${os.pretty} · family=${os.family} · ${isRoot ? "root" : "normal user (sudo on demand)"}`));
+  console.log("");
+}
+
+function supportedLinux(os = detectOS()) {
+  if (os.family !== "unsupported" && os.family !== "unknown" && os.pkg) return true;
+  console.log(c("red", `  Automated production install is not supported on ${os.pretty || os.platform}.`));
+  if (os.platform === "win32") {
+    console.log(c("yellow", "  Windows: use WSL2 Ubuntu for production, or native PowerShell for development."));
+  } else if (os.platform === "darwin") {
+    console.log(c("yellow", "  macOS: development mode only; deploy production on a supported Linux host."));
+  } else {
+    console.log(c("yellow", "  Supported Linux families: Debian/Ubuntu, RHEL/Fedora, Arch, and Alpine."));
+  }
+  console.log(c("gray", "  Guide: https://github.com/BURHANDEV-ENTERPRISE/mop-agent#platform-support\n"));
+  return false;
+}
+
+function printInstallLocations(os = detectOS()) {
+  if (!supportedLinux(os)) return false;
+  console.log(c("bold", "Installation locations"));
+  for (const [label, value] of Object.entries(installPaths(APP_DIR, os.family))) {
+    console.log(`  ${label.padEnd(15)} ${value}`);
+  }
+  console.log(c("gray", "  /var/www is not used: nginx reverse-proxies to this Node.js service.\n"));
+  return true;
+}
+
+/** Run a shell command, requesting sudo only for a privileged OS operation. */
+function run(cmd, { capture = false, privileged = false, allowFailure = false } = {}) {
+  const sudo = privileged && !isRoot;
+  const shown = `${sudo ? "sudo " : ""}${cmd}`;
+  if (DRY) { console.log(c("gray", `  [dry-run] $ ${shown}`)); return { code: 0, stdout: "" }; }
+  console.log(c("dim", `  $ ${shown}`));
+  const executable = sudo ? "sudo" : "sh";
+  const commandArgs = sudo ? ["sh", "-c", cmd] : ["-c", cmd];
+  const r = spawnSync(executable, commandArgs, {
+    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    encoding: "utf8",
+  });
+  if (!capture && r.status !== 0) console.log(c("red", `  ✗ exited ${r.status}`));
+  const code = r.status ?? 1;
+  if (code !== 0 && !allowFailure) throw new Error(`Command failed (${code}): ${shown}`);
+  return { code, stdout: r.stdout ?? "" };
+}
+
+function runSteps(steps, options = {}) {
+  for (const s of steps) {
+    console.log(c("cyan", `▸ ${s.label}`));
+    run(s.cmd, { ...options, ...s });
+  }
+}
+
+function q(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+// ---- commands ----------------------------------------------------------
+
+function cmdInstall() {
+  banner();
+  const os = detectOS();
+  if (!printInstallLocations(os)) return;
+  console.log(c("bold", "Installing system dependencies (nginx and Certbot)…\n"));
+  runSteps(planInstallDeps(os), { privileged: true });
+  console.log(c("green", "\n✓ dependencies step complete. Next: mop-agent setup\n"));
+}
+
+async function cmdSetup() {
+  banner();
+  const os = detectOS();
+  if (!printInstallLocations(os)) return;
+  const rl = createInterface({ input, output });
+  const ask = async (q, def) => (await rl.question(c("cyan", `  ${q}${def ? c("gray", ` [${def}]`) : ""}: `))).trim() || def || "";
+
+  const domain = await ask("Domain (e.g. agent.mydomain.com)");
+  const port = await ask("App port", "3000");
+  const email = await ask("Email for Let's Encrypt", domain ? `admin@${domain.split(".").slice(-2).join(".")}` : "");
+  const wantSsl = (await ask("Obtain HTTPS cert now? (y/n)", "y")).toLowerCase().startsWith("y");
+  rl.close();
+
+  if (!isValidDomain(domain)) throw new Error(`Invalid domain: ${domain || "(empty)"}`);
+  if (!isValidPort(port)) throw new Error(`Invalid port: ${port}`);
+  if (wantSsl && !isValidEmail(email)) throw new Error(`Invalid Let's Encrypt email: ${email || "(empty)"}`);
+
+  // 1) .env
+  const secret = (n) => randomToken(n);
+  const env = [
+    `PORT=${port}`,
+    `BETTER_AUTH_URL=https://${domain}`,
+    `BETTER_AUTH_SECRET=${secret(48)}`,
+    `MOP_AGENT_SECRET=${secret(64).replace(/[^0-9a-f]/g, "").padEnd(64, "0").slice(0, 64)}`,
+    `MOP_AGENT_DATA_DIR=${APP_DIR}/data`,
+    `MOP_AGENT_CONSOLIDATE_CRON=0 3 * * *`,
+  ].join("\n") + "\n";
+  console.log(c("cyan", "\n▸ Write apps/web/.env"));
+  if (DRY) console.log(c("gray", env.split("\n").map((l) => "    " + l).join("\n")));
+  else if (existsSync(`${APP_DIR}/apps/web/.env`) && !args.force) {
+    console.log(c("yellow", "  Existing .env preserved (pass --force to regenerate secrets)."));
+  } else {
+    writeFileSync(`${APP_DIR}/apps/web/.env`, env, { mode: 0o600 });
+    chmodSync(`${APP_DIR}/apps/web/.env`, 0o600);
+    console.log(c("green", "  ✓ wrote .env (mode 0600)"));
+  }
+
+  // 2) SQLite migration + production build
+  runSteps([
+    { label: "Install deps", cmd: `cd ${q(APP_DIR)} && npm ci` },
+    { label: "Migrate SQLite", cmd: `cd ${q(`${APP_DIR}/apps/web`)} && npm run db:migrate` },
+    { label: "Build", cmd: `cd ${q(`${APP_DIR}/apps/web`)} && npm run build` },
+  ]);
+
+  // 3) nginx vhost
+  const vhost = renderNginxVhost({ domain, port });
+  const nginx = nginxPaths(os.family);
+  const vhostPath = nginx.conf;
+  console.log(c("cyan", "▸ nginx reverse proxy"));
+  writeConf(vhostPath, vhost, { privileged: true });
+  runSteps([
+    ...(nginx.enabled
+      ? [{ label: "Enable site", cmd: `ln -sf ${vhostPath} ${nginx.enabled}` }]
+      : []),
+    { label: "Test nginx config", cmd: "nginx -t" },
+    { label: "Reload nginx", cmd: "systemctl reload nginx" },
+  ], { privileged: true });
+
+  // 4) systemd — run the app as the invoking user, never as root by default.
+  const serviceUser = isRoot ? process.env.SUDO_USER || "root" : process.env.USER || String(process.getuid?.() ?? "root");
+  const unit = renderSystemdUnit({ appDir: APP_DIR, port, user: serviceUser });
+  console.log(c("cyan", "▸ systemd service (auto-restart on boot)"));
+  writeConf("/etc/systemd/system/mop-agent.service", unit, { privileged: true });
+  runSteps([
+    { label: "Reload systemd", cmd: "systemctl daemon-reload" },
+    { label: "Enable + start MOP-AGENT", cmd: "systemctl enable --now mop-agent" },
+  ], { privileged: true });
+
+  // 5) SSL with a complete standalone fallback nginx configuration.
+  if (wantSsl && domain) {
+    console.log(c("cyan", "▸ HTTPS (Let's Encrypt)"));
+    const ssl = planSsl({ domain, email });
+    const { code } = run(ssl.primary.cmd, { privileged: true, allowFailure: true });
+    if (code !== 0 && !DRY) {
+      console.log(c("yellow", "  certbot --nginx failed. Scanning :80 and retrying standalone…"));
+      const scan = run(PORT80_SCAN, { capture: true, privileged: true });
+      if (scan.stdout.trim()) console.log(c("gray", "  port 80 in use by:\n" + scan.stdout.trim()));
+      runSteps(ssl.fallback, { privileged: true });
+      writeConf(vhostPath, renderNginxTlsVhost({ domain, port }), { privileged: true });
+      runSteps([
+        { label: "Test TLS nginx config", cmd: "nginx -t" },
+        { label: "Reload nginx with TLS", cmd: "systemctl reload nginx" },
+      ], { privileged: true });
+    }
+  }
+
+  console.log(c("green", `\n✓ Setup complete. Visit ${domain ? `https://${domain}` : `http://localhost:${port}`}/setup to create the owner.\n`));
+  printInstallLocations(os);
+}
+
+function cmdUpdate() {
+  banner();
+  if (!printInstallLocations()) return;
+  console.log(c("bold", "Updating MOP-AGENT…\n"));
+  runSteps([
+    ...(!managedByNpx ? [{ label: "Pull latest", cmd: `cd ${q(APP_DIR)} && git pull --ff-only` }] : []),
+    { label: "Install deps", cmd: `cd ${q(APP_DIR)} && npm ci` },
+    { label: "Migrate SQLite", cmd: `cd ${q(`${APP_DIR}/apps/web`)} && npm run db:migrate` },
+    { label: "Build", cmd: `cd ${q(`${APP_DIR}/apps/web`)} && npm run build` },
+    { label: "Restart service", cmd: "systemctl restart mop-agent", privileged: true },
+  ]);
+  console.log(c("green", "\n✓ updated\n"));
+}
+
+function cmdStatus() {
+  banner();
+  if (!printInstallLocations()) return;
+  const checks = [
+    ["service", "systemctl is-active mop-agent 2>/dev/null || echo inactive"],
+    ["nginx", "systemctl is-active nginx 2>/dev/null || echo inactive"],
+    [".env", existsSync(`${APP_DIR}/apps/web/.env`) ? "echo present" : "echo missing"],
+  ];
+  for (const [label, cmd] of checks) {
+    const r = run(cmd, { capture: true });
+    const val = DRY ? "(dry-run)" : r.stdout.trim();
+    console.log(`  ${label.padEnd(10)} ${val === "active" || val === "present" ? c("green", val) : c("yellow", val)}`);
+  }
+  console.log("");
+}
+
+function cmdUninstall() {
+  banner();
+  const os = detectOS();
+  if (!printInstallLocations(os)) return;
+  const nginx = nginxPaths(os.family);
+  const nginxRemove = [nginx.enabled, nginx.conf].filter(Boolean).join(" ");
+  console.log(c("bold", "Removing MOP-AGENT service + nginx vhost…\n"));
+  runSteps([
+    { label: "Stop + disable service", cmd: "systemctl disable --now mop-agent 2>/dev/null || true" },
+    { label: "Remove unit", cmd: "rm -f /etc/systemd/system/mop-agent.service && systemctl daemon-reload" },
+    { label: "Remove nginx vhost", cmd: `rm -f ${nginxRemove} && (systemctl reload nginx || true)` },
+  ], { privileged: true });
+  if (args.purge) {
+    console.log(c("red", "  --purge: removing SQLite brain data"));
+    runSteps([{ label: "Drop data dir", cmd: `rm -rf ${q(`${APP_DIR}/data`)}` }]);
+  } else {
+    console.log(c("gray", "  (SQLite brain data kept; pass --purge to remove)"));
+  }
+  console.log(c("green", "\n✓ uninstalled\n"));
+}
+
+// ---- helpers -----------------------------------------------------------
+
+function writeConf(path, content, { privileged = false } = {}) {
+  if (DRY) {
+    console.log(c("gray", `  [dry-run] write ${path}:`));
+    console.log(c("gray", content.split("\n").map((l) => "    " + l).join("\n")));
+    return;
+  }
+  if (privileged && !isRoot) {
+    run(`mkdir -p ${q(dirname(path))}`, { privileged: true });
+    const r = spawnSync("sudo", ["tee", path], {
+      input: content,
+      stdio: ["pipe", "ignore", "inherit"],
+      encoding: "utf8",
+    });
+    if (r.status !== 0) throw new Error(`Unable to write ${path} with sudo.`);
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+  }
+  console.log(c("green", `  ✓ wrote ${path}`));
+}
+
+function randomToken(n) {
+  return randomBytes(Math.ceil(n / 2)).toString("hex").slice(0, n);
+}
+
+async function tui() {
+  banner();
+  if (!supportedLinux()) return;
+  if (DRY) console.log(c("yellow", "  Running in DRY-RUN (no changes).\n"));
+  const rl = createInterface({ input, output });
+  const menu = [
+    ["1", "install", "Install system deps (nginx and Certbot)"],
+    ["2", "setup", "Configure domain, SQLite, SSL, systemd service"],
+    ["3", "status", "Show service health"],
+    ["4", "update", "Update to latest + restart"],
+    ["5", "uninstall", "Remove service + nginx vhost"],
+    ["q", "quit", "Exit"],
+  ];
+  for (const [k, , desc] of menu) console.log(`  ${c("cyan", k)}  ${desc}`);
+  const choice = (await rl.question(c("bold", "\n  Select: "))).trim().toLowerCase();
+  rl.close();
+  const picked = menu.find((m) => m[0] === choice || m[1] === choice);
+  if (!picked || picked[1] === "quit") return;
+  await dispatch(picked[1]);
+  return tui();
+}
+
+async function dispatch(cmd) {
+  switch (cmd) {
+    case "install": return cmdInstall();
+    case "setup": return cmdSetup();
+    case "update": return cmdUpdate();
+    case "status": case "doctor": return cmdStatus();
+    case "uninstall": case "delete": return cmdUninstall();
+    default: return tui();
+  }
+}
+
+const command = args._[0];
+(command ? dispatch(command) : tui()).catch((e) => {
+  console.error(c("red", e instanceof Error ? e.message : String(e)));
+  process.exit(1);
+});