aios-dashboard 0.2.0

package/lib/lifecycle.mjs

@@ -0,0 +1,500 @@
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { once } from "node:events";
+import { existsSync, readFileSync } from "node:fs";
+import { open, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { parseEnv } from "./env.mjs";
+import { browserCommand, dashboardPath, portableCommand } from "./paths.mjs";
+import { choosePackageManager } from "./prerequisites.mjs";
+
+const STATE_DIRECTORY = ".aios-dashboard";
+const STATE_FILE = "runtime.json";
+const LOG_FILE = "dashboard.log";
+
+export function parsePort(value = "8080") {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+  return port;
+}
+
+export async function installedDashboardPort(workspace) {
+  try {
+    const contents = await readFile(
+      path.join(dashboardPath(workspace), ".env"),
+      "utf8",
+    );
+    const value = parseEnv(contents).PORT;
+    return value ? parsePort(value) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function resolveDashboardPort({
+  workspace,
+  explicit,
+  runtime,
+} = {}) {
+  if (explicit !== undefined && explicit !== null) return parsePort(explicit);
+  if (runtime?.port !== undefined && runtime?.port !== null)
+    return parsePort(runtime.port);
+  return (await installedDashboardPort(workspace)) ?? 8080;
+}
+
+export function runtimePaths(workspace) {
+  const directory = path.join(workspace, STATE_DIRECTORY);
+  return {
+    directory,
+    state: path.join(directory, STATE_FILE),
+    log: path.join(directory, LOG_FILE),
+  };
+}
+
+export async function readRuntime(workspace) {
+  try {
+    const value = JSON.parse(
+      await readFile(runtimePaths(workspace).state, "utf8"),
+    );
+    if (
+      !Number.isInteger(value.pid) ||
+      value.pid <= 0 ||
+      !Number.isInteger(value.port) ||
+      value.port < 1 ||
+      value.port > 65_535 ||
+      value.url !== `http://127.0.0.1:${value.port}` ||
+      typeof value.processIdentity !== "string" ||
+      !value.processIdentity ||
+      !/^[a-f0-9]{64}$/.test(value.token)
+    )
+      return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+export function processAlive(pid, kill = process.kill) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    kill(pid, 0);
+    if (process.platform === "linux" && kill === process.kill) {
+      try {
+        const value = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const state = value
+          .slice(value.lastIndexOf(")") + 2)
+          .trim()
+          .split(/\s+/)[0];
+        if (state === "Z") return false;
+      } catch {
+        // A process can exit between kill(0) and reading /proc.
+        return false;
+      }
+    }
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+export function processIdentity(
+  pid,
+  { platform = process.platform, read = readFileSync, run = spawnSync } = {},
+) {
+  try {
+    if (platform === "linux") {
+      const value = read(`/proc/${pid}/stat`, "utf8");
+      const fields = value
+        .slice(value.lastIndexOf(")") + 2)
+        .trim()
+        .split(/\s+/);
+      const startedAtClockTick = fields[19];
+      return startedAtClockTick ? `linux:${startedAtClockTick}` : null;
+    }
+    if (platform === "win32") {
+      const result = run(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}').CreationDate.ToUniversalTime().Ticks`,
+        ],
+        { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], shell: false },
+      );
+      const value = result.status === 0 ? result.stdout.trim() : "";
+      return value ? `win32:${value}` : null;
+    }
+    const result = run("ps", ["-p", String(pid), "-o", "lstart="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      shell: false,
+    });
+    const value = result.status === 0 ? result.stdout.trim() : "";
+    return value ? `${platform}:${value}` : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function dashboardEndpointReady(url, fetchImpl = fetch) {
+  try {
+    const healthUrl = new URL("/_agent-native/health", url);
+    const response = await fetchImpl(healthUrl, {
+      method: "GET",
+      redirect: "manual",
+      signal: AbortSignal.timeout(1_500),
+    });
+    if (!response.ok) return false;
+    const result = await response.json();
+    return (
+      result?.ok === true &&
+      result.ready === true &&
+      result.db === true &&
+      typeof result.ms === "number" &&
+      typeof result.database?.configured === "boolean" &&
+      typeof result.database?.source === "string" &&
+      typeof result.database?.dialect === "string"
+    );
+  } catch {
+    return false;
+  }
+}
+
+function tokensMatch(actual, expected) {
+  if (typeof actual !== "string" || typeof expected !== "string") return false;
+  const left = Buffer.from(actual);
+  const right = Buffer.from(expected);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+export async function dashboardRuntimeOwned(url, token, fetchImpl = fetch) {
+  try {
+    const identityUrl = new URL("/api/aios-dashboard-runtime", url);
+    const response = await fetchImpl(identityUrl, {
+      method: "GET",
+      redirect: "manual",
+      signal: AbortSignal.timeout(1_500),
+    });
+    if (!response.ok) return false;
+    const result = await response.json();
+    return tokensMatch(result?.token, token);
+  } catch {
+    return false;
+  }
+}
+
+export async function dashboardStatus(
+  workspace,
+  {
+    kill = process.kill,
+    fetchImpl = fetch,
+    identityForPid = processIdentity,
+  } = {},
+) {
+  const runtime = await readRuntime(workspace);
+  if (!runtime) return { running: false, healthy: false, runtime: null };
+  const alive = processAlive(runtime.pid, kill);
+  const identityMatches =
+    alive && identityForPid(runtime.pid) === runtime.processIdentity;
+  const endpointOwned = await dashboardRuntimeOwned(
+    runtime.url,
+    runtime.token,
+    fetchImpl,
+  );
+  // A package-manager wrapper can exit while its Nitro child remains in the
+  // detached process group. The runtime token still proves ownership in that
+  // case; a live PID must additionally retain its OS process identity.
+  const running = endpointOwned && (!alive || identityMatches);
+  const healthy = running
+    ? await dashboardEndpointReady(runtime.url, fetchImpl)
+    : false;
+  return {
+    running,
+    healthy,
+    runtime,
+    identityMismatch: alive && !identityMatches,
+    tokenMismatch: alive && identityMatches && !endpointOwned,
+    endpointOwned,
+  };
+}
+
+export async function unmanagedDashboardReachable(
+  workspace,
+  { status = null, fetchImpl = fetch, port: explicitPort } = {},
+) {
+  const current = status ?? (await dashboardStatus(workspace, { fetchImpl }));
+  if (current.running) return false;
+  const port = await resolveDashboardPort({
+    workspace,
+    explicit: explicitPort,
+    runtime: current.runtime,
+  });
+  return dashboardEndpointReady(`http://127.0.0.1:${port}`, fetchImpl);
+}
+
+async function waitUntilReady({ url, pid, token, timeoutMs = 60_000 }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!processAlive(pid)) {
+      throw new Error("Dashboard stopped before it became ready.");
+    }
+    if (
+      (await dashboardRuntimeOwned(url, token)) &&
+      (await dashboardEndpointReady(url))
+    ) {
+      // Confirm the process survived readiness. This prevents another service
+      // already on the port from making an EADDRINUSE child look healthy.
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      if (!processAlive(pid)) {
+        throw new Error(
+          "Dashboard stopped immediately after the health check.",
+        );
+      }
+      if (
+        (await dashboardRuntimeOwned(url, token)) &&
+        (await dashboardEndpointReady(url))
+      )
+        return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 400));
+  }
+  throw new Error(
+    `Dashboard did not become ready within ${Math.ceil(timeoutMs / 1_000)} seconds.`,
+  );
+}
+
+export function killProcessTree(
+  pid,
+  signal = "SIGTERM",
+  { platform = process.platform, kill = process.kill, run = spawnSync } = {},
+) {
+  if (platform === "win32") {
+    const result = run("taskkill", ["/pid", String(pid), "/t", "/f"], {
+      stdio: "ignore",
+      shell: false,
+    });
+    return result.status === 0;
+  }
+  try {
+    // The process is launched as a detached process group, so stopping the
+    // group also stops the package-manager wrapper and the server it spawned.
+    kill(-pid, signal);
+    return true;
+  } catch {
+    try {
+      kill(pid, signal);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+async function waitForProcessExit(
+  runtime,
+  {
+    attempts,
+    kill = process.kill,
+    fetchImpl = fetch,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  },
+) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const processStopped = !processAlive(runtime.pid, kill);
+    const endpointStopped = !(await dashboardRuntimeOwned(
+      runtime.url,
+      runtime.token,
+      fetchImpl,
+    ));
+    if (processStopped && endpointStopped) return true;
+    await sleep(100);
+  }
+  return (
+    !processAlive(runtime.pid, kill) &&
+    !(await dashboardRuntimeOwned(runtime.url, runtime.token, fetchImpl))
+  );
+}
+
+export async function stopDashboard(
+  workspace,
+  {
+    kill = process.kill,
+    stopTree = killProcessTree,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    identityForPid = processIdentity,
+    fetchImpl = fetch,
+  } = {},
+) {
+  const paths = runtimePaths(workspace);
+  const runtime = await readRuntime(workspace);
+  if (!runtime) return { stopped: false, runtime: null };
+  let stopped = false;
+  const alive = processAlive(runtime.pid, kill);
+  if (alive && identityForPid(runtime.pid) !== runtime.processIdentity) {
+    throw new Error(
+      `Refusing to stop PID ${runtime.pid}: it no longer matches the Dashboard process identity. Runtime state was kept for inspection.`,
+    );
+  }
+  const endpointOwned = await dashboardRuntimeOwned(
+    runtime.url,
+    runtime.token,
+    fetchImpl,
+  );
+  if (alive && !endpointOwned) {
+    throw new Error(
+      `Refusing to stop PID ${runtime.pid}: the loopback Dashboard runtime token does not match. Runtime state was kept for inspection.`,
+    );
+  }
+  if (alive || endpointOwned) {
+    stopped = stopTree(runtime.pid, "SIGTERM", { kill });
+    let exited = await waitForProcessExit(runtime, {
+      attempts: 50,
+      kill,
+      fetchImpl,
+      sleep,
+    });
+    if (!exited) {
+      stopTree(runtime.pid, "SIGKILL", { kill });
+      exited = await waitForProcessExit(runtime, {
+        attempts: 20,
+        kill,
+        fetchImpl,
+        sleep,
+      });
+    }
+    if (!exited) {
+      throw new Error(
+        `Could not stop AIOS Dashboard process ${runtime.pid}. Runtime state was kept; stop that process and retry.`,
+      );
+    }
+  }
+  await rm(paths.state, { force: true });
+  return { stopped, runtime };
+}
+
+export async function startDashboard({
+  workspace,
+  port: portInput,
+  packageManager = choosePackageManager(),
+  timeoutMs = 60_000,
+  writeState = writeFile,
+}) {
+  const existing = await dashboardStatus(workspace);
+  if (existing.running) return { alreadyRunning: true, ...existing.runtime };
+
+  const target = dashboardPath(workspace);
+  if (!existsSync(path.join(target, "package.json"))) {
+    throw new Error(
+      `No installed Dashboard was found at ${target}. Run \`aios-dashboard init\` first.`,
+    );
+  }
+  const port = await resolveDashboardPort({
+    workspace,
+    explicit: portInput,
+    runtime: existing.runtime,
+  });
+  if (
+    await unmanagedDashboardReachable(workspace, {
+      status: existing,
+      port,
+    })
+  ) {
+    throw new Error(
+      "An AIOS Dashboard is already reachable on the configured port but is not owned by this runtime. Stop it or choose a different --port.",
+    );
+  }
+
+  const url = `http://127.0.0.1:${port}`;
+  const paths = runtimePaths(workspace);
+  await mkdir(paths.directory, { recursive: true });
+  const logHandle = await open(paths.log, "a", 0o600);
+  const args = packageManager.name === "pnpm" ? ["start"] : ["run", "start"];
+  const invocation = portableCommand(packageManager.command, [
+    ...(packageManager.commandArgs || []),
+    ...args,
+  ]);
+  const token = randomBytes(32).toString("hex");
+  let child;
+  try {
+    child = spawn(invocation.command, invocation.args, {
+      cwd: target,
+      detached: true,
+      stdio: ["ignore", logHandle.fd, logHandle.fd],
+      shell: false,
+      env: {
+        ...process.env,
+        AIOS_DASHBOARD_RUNTIME_TOKEN: token,
+        AUTH_DISABLED: "true",
+        NODE_ENV: "production",
+        HOST: "127.0.0.1",
+        NITRO_HOST: "127.0.0.1",
+        NITRO_PORT: String(port),
+        PORT: String(port),
+      },
+    });
+    await Promise.race([
+      once(child, "spawn"),
+      once(child, "error").then(([error]) => Promise.reject(error)),
+    ]);
+  } finally {
+    await logHandle.close();
+  }
+
+  if (!child?.pid)
+    throw new Error("Dashboard process did not report a process ID.");
+  const identity = processIdentity(child.pid);
+  if (!identity) {
+    killProcessTree(child.pid, "SIGKILL");
+    throw new Error(
+      "Could not verify the Dashboard process identity; it was stopped safely.",
+    );
+  }
+  child.unref();
+  const runtime = {
+    pid: child.pid,
+    port,
+    url,
+    startedAt: new Date().toISOString(),
+    log: paths.log,
+    processIdentity: identity,
+    token,
+  };
+  let stateWritten = false;
+  try {
+    await writeState(paths.state, `${JSON.stringify(runtime, null, 2)}\n`, {
+      mode: 0o600,
+    });
+    stateWritten = true;
+    await waitUntilReady({ url, pid: child.pid, token, timeoutMs });
+  } catch (error) {
+    // This is the exact child created above, so it is safe to tear the group
+    // down even when the server never became ready enough to prove its token.
+    killProcessTree(child.pid, "SIGKILL");
+    const stopped = await waitForProcessExit(runtime, {
+      attempts: 20,
+    });
+    if (!stopped) {
+      throw new Error(
+        `${error.message} The failed Dashboard process could not be stopped; ${stateWritten ? `runtime state was kept at ${paths.state}` : "no runtime state could be written"}.`,
+      );
+    }
+    if (stateWritten) await rm(paths.state, { force: true });
+    throw new Error(`${error.message} See ${paths.log}`);
+  }
+  return { alreadyRunning: false, ...runtime };
+}
+
+export function openDashboard(url) {
+  const invocation = browserCommand(url);
+  const child = spawn(invocation.command, invocation.args, {
+    detached: true,
+    stdio: "ignore",
+    shell: false,
+  });
+  child.once("error", () => undefined);
+  child.unref();
+}

package/lib/pairing.mjs

@@ -0,0 +1,107 @@
+/**
+ * The pairing secret, CLI side.
+ *
+ * This is a deliberate duplicate of `shared/agent-runner-pairing.ts`: the CLI
+ * is its own npm package shipped without a build step, so it cannot import the
+ * app's TypeScript. `shared/agent-runner-pairing.test.ts` loads both modules
+ * and asserts they encode and decode identically, so the copy cannot drift
+ * silently.
+ */
+import { randomBytes } from "node:crypto";
+
+export const PAIRING_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const PAIRING_SECRET_BYTES = 30;
+export const PAIRING_CODE_LENGTH = 48;
+export const PAIRING_GROUP_SIZE = 6;
+export const RUNNER_TOKEN_LENGTH = PAIRING_SECRET_BYTES * 2;
+export const PAIRING_LINK_SCHEME = "aios://connect";
+
+export function groupPairingCode(code) {
+  const groups = [];
+  for (let index = 0; index < code.length; index += PAIRING_GROUP_SIZE) {
+    groups.push(code.slice(index, index + PAIRING_GROUP_SIZE));
+  }
+  return groups.join("-");
+}
+
+export function normalizePairingCode(input) {
+  return String(input ?? "")
+    .toUpperCase()
+    .replace(/[^0-9A-Z]/g, "")
+    .replace(/O/g, "0")
+    .replace(/[IL]/g, "1");
+}
+
+export function encodePairingCode(bytes) {
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (const byte of bytes) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += PAIRING_ALPHABET[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += PAIRING_ALPHABET[(value << (5 - bits)) & 31];
+  return out;
+}
+
+export function decodePairingCode(input) {
+  const normalized = normalizePairingCode(input);
+  if (normalized.length !== PAIRING_CODE_LENGTH) return null;
+  let bits = 0;
+  let value = 0;
+  const bytes = [];
+  for (const character of normalized) {
+    const index = PAIRING_ALPHABET.indexOf(character);
+    if (index < 0) return null;
+    value = (value << 5) | index;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  return bytes.length === PAIRING_SECRET_BYTES ? Uint8Array.from(bytes) : null;
+}
+
+export function bytesToToken(bytes) {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export function tokenToBytes(token) {
+  const trimmed = String(token ?? "").trim().toLowerCase();
+  if (!/^[0-9a-f]+$/.test(trimmed) || trimmed.length !== RUNNER_TOKEN_LENGTH) {
+    return null;
+  }
+  const bytes = new Uint8Array(PAIRING_SECRET_BYTES);
+  for (let index = 0; index < PAIRING_SECRET_BYTES; index++) {
+    bytes[index] = Number.parseInt(trimmed.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+export function tokenFromPairingCode(code) {
+  const bytes = decodePairingCode(code);
+  return bytes ? bytesToToken(bytes) : null;
+}
+
+export function pairingCodeFromToken(token) {
+  const bytes = tokenToBytes(token);
+  return bytes ? groupPairingCode(encodePairingCode(bytes)) : null;
+}
+
+export function formatPairingLink(origin, code) {
+  return `${PAIRING_LINK_SCHEME}?origin=${encodeURIComponent(origin)}&code=${normalizePairingCode(code)}`;
+}
+
+/** A fresh runner credential in both spellings. */
+export function generatePairingSecret(random = randomBytes) {
+  const bytes = Uint8Array.from(random(PAIRING_SECRET_BYTES));
+  return {
+    token: bytesToToken(bytes),
+    code: groupPairingCode(encodePairingCode(bytes)),
+  };
+}

package/lib/paths.mjs

@@ -0,0 +1,104 @@
+import path from "node:path";
+
+export function workspacePath(input, cwd = process.cwd(), pathApi = path) {
+  return pathApi.resolve(cwd, input || ".");
+}
+
+export function dashboardPath(workspace, pathApi = path) {
+  return pathApi.join(workspace, "dashboard");
+}
+
+export function pathEntries(value, pathApi = path) {
+  return String(value || "")
+    .split(pathApi.delimiter)
+    .filter(Boolean);
+}
+
+export function executableNames(
+  command,
+  platform = process.platform,
+  // guard:allow-env-credential — executable suffix lookup for the local installer, not a credential
+  pathExt = process.env.PATHEXT,
+) {
+  if (platform !== "win32") return [command];
+  if (/\.[A-Za-z0-9]+$/.test(command)) return [command];
+  const extensions = String(pathExt || ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .filter(Boolean);
+  return extensions.map((extension) => `${command}${extension.toLowerCase()}`);
+}
+
+export function browserCommand(
+  url,
+  platform = process.platform,
+  env = process.env,
+) {
+  if (platform === "darwin") return { command: "open", args: [url] };
+  if (platform === "win32") {
+    return {
+      command: env.ComSpec || env.COMSPEC || "cmd.exe",
+      args: ["/d", "/s", "/c", "start", "", url],
+    };
+  }
+  return { command: "xdg-open", args: [url] };
+}
+
+export function portableCommand(
+  command,
+  args = [],
+  platform = process.platform,
+  env = process.env,
+) {
+  if (platform !== "win32" || !/\.(?:cmd|bat)$/i.test(command)) {
+    return { command, args };
+  }
+  return {
+    command: env.ComSpec || env.COMSPEC || "cmd.exe",
+    args: ["/d", "/s", "/c", command, ...args],
+  };
+}
+
+/**
+ * Where `connect` keeps things that must survive a reinstall.
+ *
+ * The runner credential and the runner's own auth secret live here rather than
+ * in the dashboard's `.env`, because `aios-dashboard init` replaces the app
+ * directory wholesale on update. A member who reinstalls should not have to
+ * re-pair.
+ */
+export function dataDir(
+  platform = process.platform,
+  env = process.env,
+  homedir = "",
+) {
+  const home = homedir || env.HOME || env.USERPROFILE || ".";
+  if (platform === "win32") {
+    return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "aios-dashboard");
+  }
+  if (platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "aios-dashboard");
+  }
+  return path.join(
+    env.XDG_DATA_HOME || path.join(home, ".local", "share"),
+    "aios-dashboard",
+  );
+}
+
+/** GitHub's release asset name for this machine, or null when unsupported. */
+export function cloudflaredAssetName(
+  platform = process.platform,
+  arch = process.arch,
+) {
+  const architectures = { x64: "amd64", arm64: "arm64", arm: "arm" };
+  const cpu = architectures[arch];
+  if (!cpu) return null;
+  if (platform === "linux") return `cloudflared-linux-${cpu}`;
+  if (platform === "darwin") return `cloudflared-darwin-${cpu}.tgz`;
+  if (platform === "win32") return `cloudflared-windows-${cpu === "amd64" ? "amd64" : cpu}.exe`;
+  return null;
+}
+
+/** An absolute candidate path, when something is actually there. */
+export function findExecutableOrNull(candidate, exists) {
+  return exists(candidate) ? candidate : null;
+}