aios-dashboard 0.2.0

package/lib/installer.mjs

@@ -0,0 +1,698 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import {
+  chmod,
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { installerEnv, mergeEnv, redactDatabaseUrl } from "./env.mjs";
+import {
+  dashboardStatus,
+  openDashboard,
+  resolveDashboardPort,
+  startDashboard,
+  stopDashboard,
+  unmanagedDashboardReachable,
+} from "./lifecycle.mjs";
+import { dashboardPath, portableCommand, workspacePath } from "./paths.mjs";
+import {
+  choosePackageManager,
+  databaseReachable,
+  findExecutable,
+  missingNativeBuildTools,
+  MINIMUM_NODE_VERSION,
+  supportsNode,
+  workspaceDatabaseUrl,
+  workspacePresent,
+} from "./prerequisites.mjs";
+import { downloadSource, normalizeSha256, redactSource } from "./source.mjs";
+import { extractZip, findSourceRoot } from "./zip.mjs";
+
+export const MEMBER_OWNED_PATHS = ["data", "learnings.md"];
+
+export function parseArgs(argv) {
+  const options = {
+    command: null,
+    dir: null,
+    ref: null,
+    source: null,
+    sourceSha256: null,
+    start: false,
+    dryRun: false,
+    yes: false,
+    help: false,
+    // `connect`
+    port: null,
+    tunnelUrl: null,
+    tunnelName: null,
+    tunnelHostname: null,
+    noDownload: false,
+    rotate: false,
+    daemon: false,
+    printPairing: false,
+  };
+  const args = [...argv];
+  if (args[0] && !args[0].startsWith("-")) options.command = args.shift();
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === "--dir") options.dir = requiredValue(arg, args.shift());
+    else if (arg === "--ref") options.ref = requiredValue(arg, args.shift());
+    else if (arg === "--source")
+      options.source = requiredValue(arg, args.shift());
+    else if (arg === "--source-sha256")
+      options.sourceSha256 = requiredValue(arg, args.shift());
+    else if (arg === "--start") options.start = true;
+    else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--yes" || arg === "-y") options.yes = true;
+    else if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--port") options.port = requiredValue(arg, args.shift());
+    else if (arg === "--tunnel-url")
+      options.tunnelUrl = requiredValue(arg, args.shift());
+    else if (arg === "--tunnel-name")
+      options.tunnelName = requiredValue(arg, args.shift());
+    else if (arg === "--tunnel-hostname")
+      options.tunnelHostname = requiredValue(arg, args.shift());
+    else if (arg === "--no-download") options.noDownload = true;
+    else if (arg === "--rotate") options.rotate = true;
+    else if (arg === "--daemon") options.daemon = true;
+    else if (arg === "--print-pairing") options.printPairing = true;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  return options;
+}
+
+function requiredValue(flag, value) {
+  if (!value || value.startsWith("-"))
+    throw new Error(`${flag} requires a value.`);
+  return value;
+}
+
+export function helpText() {
+  return `AIOS Dashboard
+
+Usage:
+  aios-dashboard init    [--dir <workspace>] [--source <url-or-path> --source-sha256 <hash>] [--start]
+  aios-dashboard start   [--dir <workspace>] [--port <port>]
+  aios-dashboard open    [--dir <workspace>] [--port <port>]
+  aios-dashboard status  [--dir <workspace>]
+  aios-dashboard stop    [--dir <workspace>]
+  aios-dashboard connect [--dir <workspace>] [--port <port>]
+
+Commands:
+  init     Install the Dashboard into an AIOS workspace
+  start    Start the installed production Dashboard in the background
+  open     Open the installed Dashboard in a browser
+  status   Show whether the local Dashboard is running
+  stop     Stop the local Dashboard
+  connect  Let a hosted Dashboard run Claude Code on this computer
+
+Options for init:
+  --dir <workspace>  AIOS workspace (default: current directory)
+  --ref <tag>        Install a specific Git tag/branch from GitHub
+  --source <value>   Install an MCP URL, file URL, or local release ZIP
+  --source-sha256    Required SHA-256 for --source (64 hexadecimal characters)
+  --start            Build, start the production dashboard on loopback, and open it
+  --yes, -y          Accept every prompt without asking
+
+Options for connect:
+  --port <port>          Local port for the runner (default: 8099)
+  --tunnel-url <origin>  Use a tunnel you already run instead of cloudflared
+  --tunnel-name <name>   Run a named Cloudflare tunnel instead of a quick one
+  --rotate               Mint a new pairing code, invalidating the old one
+  --daemon               Install a user service so it survives a reboot
+  Run \`aios-dashboard connect --help\` for the full list.
+
+Shared options:
+  --dry-run          Print the plan without changing anything
+  --help, -h         Show this help
+`;
+}
+
+export function npxLifecycleCommand(version, command, workspace) {
+  return npxLifecycleCommandForPlatform(version, command, workspace);
+}
+
+function shellQuote(value, platform) {
+  const text = String(value);
+  return platform === "win32"
+    ? `'${text.replaceAll("'", "''")}'`
+    : `'${text.replaceAll("'", `'"'"'`)}'`;
+}
+
+export function npxLifecycleCommandForPlatform(
+  version,
+  command,
+  workspace,
+  platform = process.platform,
+) {
+  const executable = platform === "win32" ? "npx.cmd" : "npx";
+  return `${executable} --yes --package aios-dashboard@${version} aios-dashboard ${command} --dir ${shellQuote(workspace, platform)}`;
+}
+
+async function confirm(question, fallback = true) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return fallback;
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    const answer = (await prompt.question(`${question} [Y/n] `))
+      .trim()
+      .toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  } finally {
+    prompt.close();
+  }
+}
+
+async function preflight(options) {
+  if (!supportsNode()) {
+    throw new Error(`Node.js ${MINIMUM_NODE_VERSION} or newer is required.`);
+  }
+  const workspace = workspacePath(options.dir);
+  const target = dashboardPath(workspace);
+  const hasWorkspace = workspacePresent(workspace);
+  if (!hasWorkspace && !options.yes) {
+    const proceed = await confirm(
+      "No AIOS workspace (CLAUDE.md + context/) was found. Continue anyway?",
+    );
+    if (!proceed) throw new Error("Installation cancelled.");
+  }
+
+  const configuredUrl = workspaceDatabaseUrl(workspace);
+  const databaseUrl = configuredUrl;
+  let databaseReachableNow = false;
+  if (configuredUrl) {
+    const reachable = options.dryRun
+      ? true
+      : await databaseReachable(configuredUrl);
+    databaseReachableNow = reachable;
+    if (!reachable) {
+      console.warn(
+        "! Member Supabase is configured but not reachable; the dashboard will show its not-connected states.",
+      );
+      if (!options.yes) {
+        const proceed = await confirm(
+          "Keep the configured URL and continue while it is unreachable?",
+        );
+        if (!proceed) throw new Error("Installation cancelled.");
+      }
+    }
+  }
+
+  const missingBuildTools = missingNativeBuildTools();
+  if (missingBuildTools.length > 0) {
+    throw new Error(
+      `Linux native build prerequisites are missing: ${missingBuildTools.join(", ")}. Install Python 3, make, and a C/C++ toolchain (for example, the build-essential package), then retry.`,
+    );
+  }
+  const packageManager = choosePackageManager();
+  const claude = findExecutable("claude");
+  return {
+    workspace,
+    target,
+    hasWorkspace,
+    databaseUrl,
+    databaseReachableNow,
+    packageManager,
+    claude,
+  };
+}
+
+function printPlan(context, options, version) {
+  const source = options.source
+    ? redactSource(options.source)
+    : options.ref
+      ? `GitHub ref ${options.ref}`
+      : `release v${version}`;
+  console.log("\nAIOS Dashboard install plan");
+  console.log(`  Source:       ${source}`);
+  console.log(
+    `  Integrity:    ${options.sourceSha256 ? `SHA-256 ${options.sourceSha256}` : "GitHub release transport"}`,
+  );
+  console.log(`  Workspace:    ${context.workspace}`);
+  console.log(`  Destination:  ${context.target}`);
+  console.log(
+    `  Mode:         ${
+      context.databaseUrl
+        ? context.databaseReachableNow
+          ? "local + member Supabase"
+          : "local + configured member Supabase (currently unreachable)"
+        : "local, no member database"
+    }`,
+  );
+  console.log(`  Database:     ${redactDatabaseUrl(context.databaseUrl)}`);
+  console.log(
+    `  Dependencies: pnpm install --frozen-lockfile --prod=false (pnpm ${context.packageManager.version || "10.30.3"})`,
+  );
+  console.log(
+    `  Claude CLI:   ${context.claude ? "found" : "not found (warning only)"}`,
+  );
+  if (existsSync(context.target))
+    console.log(
+      "  Update:       replace app files; preserve .env, data/, and learnings.md",
+    );
+  console.log("");
+}
+
+function runPackageCommand(context, cwd, args, label) {
+  const invocation = portableCommand(context.packageManager.command, [
+    ...(context.packageManager.commandArgs || []),
+    ...args,
+  ]);
+  const result = spawnSync(invocation.command, invocation.args, {
+    cwd,
+    stdio: "inherit",
+    shell: false,
+    env: process.env,
+  });
+  if (result.status !== 0) {
+    throw new Error(`${label} failed with exit code ${result.status}.`);
+  }
+}
+
+export async function ensureNodePtyHelperExecutable(
+  cwd,
+  { platform = process.platform, arch = process.arch } = {},
+) {
+  if (platform !== "darwin") return false;
+  const helper = path.join(
+    cwd,
+    "node_modules",
+    "node-pty",
+    "prebuilds",
+    `darwin-${arch}`,
+    "spawn-helper",
+  );
+  if (!existsSync(helper)) {
+    throw new Error(
+      `node-pty did not install its macOS ${arch} spawn-helper at the expected path.`,
+    );
+  }
+  await chmod(helper, 0o755);
+  return true;
+}
+
+async function assertSafeMemberPath(candidate, relative) {
+  const info = await lstat(candidate);
+  if (info.isSymbolicLink()) {
+    throw new Error(
+      `Refusing to preserve member-owned ${relative}: symbolic links are not allowed in Dashboard local data.`,
+    );
+  }
+  if (info.isDirectory()) {
+    for (const entry of await readdir(candidate)) {
+      await assertSafeMemberPath(
+        path.join(candidate, entry),
+        path.join(relative, entry),
+      );
+    }
+    return;
+  }
+  if (!info.isFile()) {
+    throw new Error(
+      `Refusing to preserve unsupported member-owned path: ${relative}`,
+    );
+  }
+}
+
+export async function preserveMemberData(existingTarget, stagedTarget) {
+  if (!existsSync(existingTarget)) return [];
+  const preserved = [];
+  for (const relative of MEMBER_OWNED_PATHS) {
+    const source = path.join(existingTarget, relative);
+    if (!existsSync(source)) continue;
+    await assertSafeMemberPath(source, relative);
+    await cp(source, path.join(stagedTarget, relative), {
+      recursive: true,
+      dereference: false,
+      force: true,
+    });
+    preserved.push(relative);
+  }
+  return preserved;
+}
+
+export async function removeBackupAfterCommit(
+  backup,
+  { remove = rm, warn = console.warn } = {},
+) {
+  try {
+    await remove(backup, { recursive: true, force: true });
+    return true;
+  } catch (error) {
+    warn(
+      `! The verified Dashboard is installed, but its previous-version backup could not be removed at ${backup}: ${error.message}`,
+    );
+    return false;
+  }
+}
+
+export function assertUpdateRuntimeSafe(status) {
+  if (status.identityMismatch) {
+    throw new Error(
+      `Refusing to update while Dashboard runtime state points at reused PID ${status.runtime.pid}. It will not be signalled; inspect ${status.runtime.log}, remove the stale runtime state only after confirming the old Dashboard is stopped, then retry.`,
+    );
+  }
+  if (status.tokenMismatch) {
+    throw new Error(
+      `Refusing to update while Dashboard process ${status.runtime.pid} is alive but runtime ownership cannot be verified. Stop that Dashboard manually, then retry; its runtime state was kept for inspection.`,
+    );
+  }
+}
+
+async function installSource(
+  context,
+  buffer,
+  beforeSwap = async () => undefined,
+) {
+  await mkdir(context.workspace, { recursive: true });
+  const temporary = await mkdtemp(
+    path.join(os.tmpdir(), "aios-dashboard-install-"),
+  );
+  const extracted = path.join(temporary, "archive");
+  const staged = path.join(
+    context.workspace,
+    `.dashboard-stage-${process.pid}-${Date.now()}`,
+  );
+  const backup = path.join(
+    context.workspace,
+    `.dashboard-backup-${process.pid}-${Date.now()}`,
+  );
+  let movedExisting = false;
+  try {
+    await extractZip(buffer, extracted);
+    const sourceRoot = await findSourceRoot(extracted);
+    await cp(sourceRoot, staged, { recursive: true, dereference: true });
+
+    let existingEnv = "";
+    if (existsSync(path.join(context.target, ".env"))) {
+      existingEnv = await readFile(path.join(context.target, ".env"), "utf8");
+    }
+    const nextEnv = mergeEnv(
+      existingEnv,
+      installerEnv({
+        workspace: context.workspace,
+        databaseUrl: context.databaseUrl,
+      }),
+      { replaceBlankKeys: ["AIOS_DASHBOARD_DB_URL"] },
+    );
+    await writeFile(path.join(staged, ".env"), nextEnv, { mode: 0o600 });
+
+    runPackageCommand(
+      context,
+      staged,
+      context.packageManager.installArgs,
+      `${context.packageManager.name} install`,
+    );
+    await ensureNodePtyHelperExecutable(staged);
+    runPackageCommand(
+      context,
+      staged,
+      context.packageManager.name === "pnpm" ? ["build"] : ["run", "build"],
+      `${context.packageManager.name} build`,
+    );
+
+    await beforeSwap();
+    const preserved = await preserveMemberData(context.target, staged);
+    if (preserved.length > 0) {
+      console.log(
+        `Preserved member-owned local data: ${preserved.join(", ")}.`,
+      );
+    }
+    if (existsSync(context.target)) {
+      await rename(context.target, backup);
+      movedExisting = true;
+    }
+    await rename(staged, context.target);
+    return {
+      movedExisting,
+      async commit() {
+        if (movedExisting) await removeBackupAfterCommit(backup);
+      },
+      async rollback() {
+        if (!movedExisting || !existsSync(backup)) return false;
+        await rm(context.target, { recursive: true, force: true });
+        await rename(backup, context.target);
+        return true;
+      },
+    };
+  } catch (error) {
+    await rm(staged, { recursive: true, force: true }).catch(() => undefined);
+    if (movedExisting && existsSync(backup)) {
+      await rm(context.target, { recursive: true, force: true }).catch(
+        () => undefined,
+      );
+      await rename(backup, context.target).catch(() => undefined);
+    }
+    throw error;
+  } finally {
+    await rm(temporary, { recursive: true, force: true }).catch(
+      () => undefined,
+    );
+  }
+}
+
+async function runLifecycleCommand(options) {
+  const workspace = workspacePath(options.dir);
+  if (!supportsNode()) {
+    throw new Error(`Node.js ${MINIMUM_NODE_VERSION} or newer is required.`);
+  }
+  if (options.command === "status") {
+    const status = await dashboardStatus(workspace);
+    if (!status.running) {
+      if (status.identityMismatch) {
+        console.log(
+          `AIOS Dashboard runtime state is stale: PID ${status.runtime.pid} belongs to another process. It will not be signalled.`,
+        );
+        return;
+      }
+      if (status.tokenMismatch) {
+        console.log(
+          `AIOS Dashboard runtime ownership could not be verified at ${status.runtime.url}. It will not be signalled.`,
+        );
+        return;
+      }
+      console.log("AIOS Dashboard is stopped.");
+      return;
+    }
+    console.log(
+      `AIOS Dashboard is ${status.healthy ? "running" : "starting or unhealthy"} at ${status.runtime.url} (PID ${status.runtime.pid}).`,
+    );
+    console.log(`Logs: ${status.runtime.log}`);
+    return;
+  }
+  if (options.command === "stop") {
+    if (options.dryRun) {
+      console.log(`Would stop the AIOS Dashboard for ${workspace}.`);
+      return;
+    }
+    const result = await stopDashboard(workspace);
+    console.log(
+      result.runtime
+        ? "AIOS Dashboard stopped."
+        : "AIOS Dashboard is already stopped.",
+    );
+    return;
+  }
+  const existing = await dashboardStatus(workspace);
+  const port = await resolveDashboardPort({
+    workspace,
+    explicit: options.port,
+    runtime: existing.runtime,
+  });
+  const url = existing.runtime?.url || `http://127.0.0.1:${port}`;
+  if (options.command === "open") {
+    if (options.dryRun) {
+      console.log(`Would open ${url}.`);
+      return;
+    }
+    openDashboard(url);
+    console.log(`Opened ${url}.`);
+    return;
+  }
+  if (options.command === "start") {
+    if (options.dryRun) {
+      console.log(`Would start the production Dashboard at ${url}.`);
+      return;
+    }
+    const runtime = await startDashboard({ workspace, port });
+    console.log(
+      runtime.alreadyRunning
+        ? `AIOS Dashboard is already running at ${runtime.url}.`
+        : `AIOS Dashboard started at ${runtime.url}.`,
+    );
+    console.log(`Logs: ${runtime.log}`);
+  }
+}
+
+export async function runInstaller(options, version) {
+  if (!options.command || (options.help && !options.command)) {
+    console.log(helpText());
+    return;
+  }
+  if (options.command === "connect") {
+    const { runConnect } = await import("./connect.mjs");
+    await runConnect(options);
+    return;
+  }
+  if (options.help) {
+    console.log(helpText());
+    return;
+  }
+  if (["start", "open", "status", "stop"].includes(options.command)) {
+    await runLifecycleCommand(options);
+    return;
+  }
+  if (options.command !== "init")
+    throw new Error(`Unknown command: ${options.command}`);
+  if (options.sourceSha256)
+    options.sourceSha256 = normalizeSha256(options.sourceSha256);
+  if (options.source && !options.sourceSha256) {
+    throw new Error(
+      "--source requires --source-sha256 so the artifact can be verified.",
+    );
+  }
+  if (options.sourceSha256 && !options.source) {
+    throw new Error("--source-sha256 can only be used with --source.");
+  }
+  if (!options.source && !options.ref) {
+    throw new Error(
+      "Dashboard releases are member-only. Ask Claude to install AIOS so the MCP can provide an entitled --source and --source-sha256. Maintainers may use --ref for development.",
+    );
+  }
+  const context = await preflight(options);
+  printPlan(context, options, version);
+  if (options.dryRun) {
+    console.log("Dry run complete; no files were changed.");
+    return;
+  }
+  if (!context.claude) {
+    console.warn(
+      "! Claude CLI was not found. The dashboard will work, but local chat/commands will not.",
+    );
+  }
+  const buffer = await downloadSource({
+    version,
+    ref: options.ref,
+    source: options.source,
+    sourceSha256: options.sourceSha256,
+  });
+  let wasRunning = false;
+  let previousRuntime = null;
+  let transaction;
+  try {
+    transaction = await installSource(context, buffer, async () => {
+      const status = await dashboardStatus(context.workspace);
+      assertUpdateRuntimeSafe(status);
+      if (
+        existsSync(context.target) &&
+        !status.running &&
+        (await unmanagedDashboardReachable(context.workspace, { status }))
+      ) {
+        throw new Error(
+          "An older AIOS Dashboard is running without managed runtime state. Stop its dev server or terminal first, then run the update again.",
+        );
+      }
+      wasRunning = status.running;
+      previousRuntime = status.runtime;
+      if (wasRunning) {
+        console.log("Stopping the current Dashboard for the atomic update…");
+        await stopDashboard(context.workspace);
+      }
+    });
+  } catch (error) {
+    if (wasRunning) {
+      await startDashboard({
+        workspace: context.workspace,
+        packageManager: context.packageManager,
+        port: previousRuntime?.port,
+      }).catch((restartError) => {
+        console.warn(
+          `! Previous Dashboard was restored but could not restart: ${restartError.message}`,
+        );
+      });
+    }
+    throw error;
+  }
+
+  try {
+    let runtime = null;
+    if (options.start || wasRunning || transaction.movedExisting) {
+      runtime = await startDashboard({
+        workspace: context.workspace,
+        packageManager: context.packageManager,
+        port: options.port || previousRuntime?.port,
+      });
+    }
+    if (runtime && transaction.movedExisting && !options.start && !wasRunning) {
+      console.log(
+        "The replacement Dashboard passed production health; stopping it because it was not running before the update…",
+      );
+      await stopDashboard(context.workspace);
+      runtime = null;
+    }
+    await transaction.commit();
+    console.log("AIOS Dashboard installed successfully.");
+    if (runtime) {
+      console.log(`AIOS Dashboard started at ${runtime.url}.`);
+      console.log(`Logs: ${runtime.log}`);
+      if (options.start) openDashboard(runtime.url);
+    } else {
+      console.log(
+        `\nStart it later with:\n  ${npxLifecycleCommand(version, "start", context.workspace)}`,
+      );
+    }
+    console.log(
+      "\nAUTH_DISABLED=true is for this local, single-user install only. Never use it on a public hosted copy.",
+    );
+  } catch (error) {
+    if (transaction.movedExisting) {
+      try {
+        await stopDashboard(context.workspace);
+        const stoppedStatus = await dashboardStatus(context.workspace);
+        if (
+          stoppedStatus.running ||
+          stoppedStatus.identityMismatch ||
+          stoppedStatus.tokenMismatch ||
+          (await unmanagedDashboardReachable(context.workspace, {
+            status: stoppedStatus,
+            port: options.port || previousRuntime?.port,
+          }))
+        ) {
+          throw new Error(
+            "the replacement Dashboard could not be proven stopped",
+          );
+        }
+      } catch (stopError) {
+        throw new Error(
+          `${error.message} Rollback was not attempted because ${stopError.message}. The replacement and previous-version backup were kept for safe manual recovery.`,
+        );
+      }
+      const restored = await transaction.rollback();
+      if (restored && wasRunning) {
+        await startDashboard({
+          workspace: context.workspace,
+          packageManager: context.packageManager,
+          port: previousRuntime?.port,
+        }).catch((restartError) => {
+          console.warn(
+            `! Previous Dashboard was restored but could not restart: ${restartError.message}`,
+          );
+        });
+      }
+    }
+    throw error;
+  }
+}