aios-dashboard 0.2.0

package/lib/prerequisites.mjs

@@ -0,0 +1,183 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+
+import { parseEnv } from "./env.mjs";
+import { executableNames, pathEntries, portableCommand } from "./paths.mjs";
+
+export const MINIMUM_NODE_VERSION = "22.22.0";
+export const PNPM_VERSION = "10.30.3";
+
+export function nodeVersion(version = process.versions.node) {
+  const match = String(version || "").match(/^(?:v)?(\d+)\.(\d+)\.(\d+)/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+export function nodeMajor(version = process.versions.node) {
+  return nodeVersion(version)?.[0] ?? Number.NaN;
+}
+
+export function supportsNode(
+  version = process.versions.node,
+  minimum = MINIMUM_NODE_VERSION,
+) {
+  const current = nodeVersion(version);
+  const required = nodeVersion(minimum);
+  if (!current || !required) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (current[index] > required[index]) return true;
+    if (current[index] < required[index]) return false;
+  }
+  return true;
+}
+
+export function findExecutable(
+  command,
+  {
+    env = process.env,
+    platform = process.platform,
+    pathApi = platform === "win32" ? path.win32 : path,
+    access = accessSync,
+  } = {},
+) {
+  const names = executableNames(command, platform, env.PATHEXT);
+  const dirs = pathEntries(env.PATH, pathApi);
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = pathApi.join(dir, name);
+      try {
+        access(
+          candidate,
+          platform === "win32" ? constants.F_OK : constants.X_OK,
+        );
+        return candidate;
+      } catch {
+        // Try the next PATH entry.
+      }
+    }
+  }
+  return null;
+}
+
+export function workspacePresent(workspace) {
+  return (
+    existsSync(path.join(workspace, "CLAUDE.md")) &&
+    existsSync(path.join(workspace, "context"))
+  );
+}
+
+export function workspaceDatabaseUrl(workspace, env = process.env) {
+  if (env.AIOS_DASHBOARD_DB_URL?.trim()) {
+    return env.AIOS_DASHBOARD_DB_URL.trim();
+  }
+  const envPath = path.join(workspace, ".env");
+  if (!existsSync(envPath)) return null;
+  const parsed = parseEnv(readFileSync(envPath, "utf8"));
+  return parsed.AIOS_DASHBOARD_DB_URL?.trim() || null;
+}
+
+export function choosePackageManager({
+  env = process.env,
+  run = spawnSync,
+} = {}) {
+  const pnpm = findExecutable("pnpm", { env });
+  if (pnpm) {
+    const invocation = portableCommand(
+      pnpm,
+      ["--version"],
+      process.platform,
+      env,
+    );
+    const version = run(invocation.command, invocation.args, {
+      encoding: "utf8",
+      env,
+      stdio: ["ignore", "pipe", "ignore"],
+      shell: false,
+    });
+    if (version.status === 0 && version.stdout.trim() === PNPM_VERSION) {
+      return {
+        name: "pnpm",
+        version: PNPM_VERSION,
+        command: pnpm,
+        commandArgs: [],
+        installArgs: ["install", "--frozen-lockfile", "--prod=false"],
+      };
+    }
+  }
+
+  const corepack = findExecutable("corepack", { env });
+  if (corepack) {
+    return {
+      name: "pnpm",
+      version: PNPM_VERSION,
+      command: corepack,
+      commandArgs: [`pnpm@${PNPM_VERSION}`],
+      installArgs: ["install", "--frozen-lockfile", "--prod=false"],
+    };
+  }
+
+  const npm = findExecutable("npm", { env });
+  if (npm) {
+    return {
+      name: "pnpm",
+      version: PNPM_VERSION,
+      command: npm,
+      commandArgs: [
+        "exec",
+        "--yes",
+        `--package=pnpm@${PNPM_VERSION}`,
+        "--",
+        "pnpm",
+      ],
+      installArgs: ["install", "--frozen-lockfile", "--prod=false"],
+    };
+  }
+  throw new Error(
+    `pnpm ${PNPM_VERSION} is required. Install pnpm, Corepack, or npm so the installer can invoke the pinned version.`,
+  );
+}
+
+export function missingNativeBuildTools({
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  if (platform !== "linux") return [];
+  const missing = [];
+  if (!findExecutable("python3", { env })) missing.push("Python 3");
+  if (!findExecutable("make", { env })) missing.push("make");
+  if (
+    !findExecutable("c++", { env }) &&
+    !findExecutable("g++", { env }) &&
+    !findExecutable("clang++", { env })
+  ) {
+    missing.push("a C/C++ compiler");
+  }
+  return missing;
+}
+
+export async function databaseReachable(value, timeoutMs = 4_000) {
+  if (!value) return false;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (!new Set(["postgres:", "postgresql:"]).has(url.protocol)) return false;
+  const port = Number(url.port || 5432);
+  if (!url.hostname || !Number.isInteger(port)) return false;
+
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host: url.hostname, port });
+    const done = (result) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}

package/lib/service.mjs

@@ -0,0 +1,141 @@
+/**
+ * `--daemon`: keep the runner connected across reboots.
+ *
+ * A user-level service, never a system one. The runner needs the member's own
+ * logged-in `claude`, their home directory and their workspace — running it as
+ * root or as another user would either fail or, worse, half-work.
+ *
+ * The unit is written and enabled, then the exact commands to inspect or
+ * remove it are printed. Nothing here touches sudo.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+import { dataDir } from "./paths.mjs";
+
+export const SERVICE_NAME = "aios-dashboard-connect";
+export const LAUNCHD_LABEL = "ai.aios.dashboard.connect";
+
+/** The `connect` invocation the service repeats, minus `--daemon` itself. */
+export function serviceArguments({ workspace, port, options = {} }) {
+  const args = ["connect", "--dir", workspace, "--port", String(port)];
+  if (options.tunnelUrl) args.push("--tunnel-url", options.tunnelUrl);
+  if (options.tunnelName) args.push("--tunnel-name", options.tunnelName);
+  if (options.tunnelHostname) args.push("--tunnel-hostname", options.tunnelHostname);
+  if (options.noDownload) args.push("--no-download");
+  return args;
+}
+
+export function systemdUnit({ execPath, script, args, workspace, logDir }) {
+  const command = [execPath, script, ...args]
+    .map((part) => (/[\s"']/.test(part) ? JSON.stringify(part) : part))
+    .join(" ");
+  return `[Unit]
+Description=AIOS Dashboard — connect this computer to a hosted dashboard
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${workspace}
+ExecStart=${command}
+Restart=always
+RestartSec=10
+StandardOutput=append:${path.join(logDir, "connect.log")}
+StandardError=append:${path.join(logDir, "connect.log")}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function launchdPlist({ execPath, script, args, workspace, logDir }) {
+  const programArguments = [execPath, script, ...args]
+    .map((part) => `    <string>${part.replace(/&/g, "&amp;").replace(/</g, "&lt;")}</string>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArguments}
+  </array>
+  <key>WorkingDirectory</key><string>${workspace}</string>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${path.join(logDir, "connect.log")}</string>
+  <key>StandardErrorPath</key><string>${path.join(logDir, "connect.log")}</string>
+</dict>
+</plist>
+`;
+}
+
+export async function installConnectService({
+  workspace,
+  port,
+  options = {},
+  log = console.log,
+  platform = process.platform,
+  env = process.env,
+  execPath = process.execPath,
+  script = process.argv[1],
+  run = spawnSync,
+}) {
+  const logDir = path.join(dataDir(platform, env), "logs");
+  await mkdir(logDir, { recursive: true });
+  const args = serviceArguments({ workspace, port, options });
+
+  if (platform === "linux") {
+    const unitDir = path.join(
+      env.XDG_CONFIG_HOME || path.join(env.HOME || ".", ".config"),
+      "systemd",
+      "user",
+    );
+    await mkdir(unitDir, { recursive: true });
+    const unitPath = path.join(unitDir, `${SERVICE_NAME}.service`);
+    await writeFile(unitPath, systemdUnit({ execPath, script, args, workspace, logDir }));
+    const result = run("systemctl", ["--user", "enable", "--now", SERVICE_NAME], {
+      stdio: "inherit",
+      shell: false,
+    });
+    log(`\nService installed at ${unitPath}`);
+    if (result.status !== 0) {
+      log("systemctl could not enable it here. Run this once you have a user session:");
+      log(`  systemctl --user enable --now ${SERVICE_NAME}`);
+    }
+    log(`  Status  systemctl --user status ${SERVICE_NAME}`);
+    log(`  Logs    tail -f ${path.join(logDir, "connect.log")}`);
+    log(`  Remove  systemctl --user disable --now ${SERVICE_NAME} && rm ${unitPath}`);
+    log(
+      "\nThe pairing block is in the log. Reboots keep the pairing code; a quick tunnel gets a new address, so re-paste after one.",
+    );
+    return { path: unitPath };
+  }
+
+  if (platform === "darwin") {
+    const agentDir = path.join(env.HOME || ".", "Library", "LaunchAgents");
+    await mkdir(agentDir, { recursive: true });
+    const plistPath = path.join(agentDir, `${LAUNCHD_LABEL}.plist`);
+    await writeFile(plistPath, launchdPlist({ execPath, script, args, workspace, logDir }));
+    run("launchctl", ["unload", plistPath], { stdio: "ignore", shell: false });
+    const result = run("launchctl", ["load", plistPath], { stdio: "inherit", shell: false });
+    log(`\nService installed at ${plistPath}`);
+    if (result.status !== 0) {
+      log("launchctl could not load it here. Run this once you are signed in:");
+      log(`  launchctl load ${plistPath}`);
+    }
+    log(`  Logs    tail -f ${path.join(logDir, "connect.log")}`);
+    log(`  Remove  launchctl unload ${plistPath} && rm ${plistPath}`);
+    log(
+      "\nThe pairing block is in the log. Reboots keep the pairing code; a quick tunnel gets a new address, so re-paste after one.",
+    );
+    return { path: plistPath };
+  }
+
+  throw new Error(
+    `--daemon supports macOS and Linux. On ${platform}, run \`aios-dashboard connect\` in a terminal you leave open.`,
+  );
+}

package/lib/source.mjs

@@ -0,0 +1,245 @@
+import { spawnSync } from "node:child_process";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const REPOSITORY = "niknorf/aios-dashboard";
+export const MAX_SOURCE_BYTES = 250 * 1024 * 1024;
+export const SOURCE_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1_000;
+
+export function releaseAssetUrl(version) {
+  return `https://github.com/${REPOSITORY}/releases/download/v${version}/aios-dashboard-${version}.zip`;
+}
+
+export function refZipUrl(ref) {
+  const encoded = String(ref)
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+  return `https://codeload.github.com/${REPOSITORY}/zip/${encoded}`;
+}
+
+function githubToken(env = process.env) {
+  const explicit = env.GH_TOKEN || env.GITHUB_TOKEN;
+  if (explicit?.trim()) return explicit.trim();
+  const result = spawnSync("gh", ["auth", "token"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    shell: false,
+  });
+  return result.status === 0 ? result.stdout.trim() : "";
+}
+
+export function redactSource(value) {
+  if (!/^https?:\/\//i.test(value)) return value;
+  try {
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return "remote source";
+  }
+}
+
+export function normalizeSha256(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(normalized)) {
+    throw new Error(
+      "--source-sha256 must be exactly 64 hexadecimal characters.",
+    );
+  }
+  return normalized;
+}
+
+export function sha256(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+export function verifySourceSha256(buffer, expected) {
+  const normalized = normalizeSha256(expected);
+  const actual = sha256(buffer);
+  if (
+    !timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(normalized, "hex"))
+  ) {
+    throw new Error(
+      `Dashboard source failed SHA-256 verification (expected ${normalized}, received ${actual}).`,
+    );
+  }
+  return actual;
+}
+
+export async function fetchBuffer(
+  input,
+  {
+    token = "",
+    sameOriginRedirectsOnly = false,
+    maxRedirects = 5,
+    timeoutMs = SOURCE_DOWNLOAD_TIMEOUT_MS,
+    fetchImpl = fetch,
+  } = {},
+) {
+  let original;
+  try {
+    original = new URL(input);
+  } catch {
+    throw new Error(`Invalid Dashboard source URL (${redactSource(input)}).`);
+  }
+  let current = original;
+  const deadline = Date.now() + timeoutMs;
+  for (let redirect = 0; redirect <= maxRedirects; redirect += 1) {
+    const sameOrigin = current.origin === original.origin;
+    try {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw new DOMException("Timed out", "TimeoutError");
+      const response = await fetchImpl(current, {
+        redirect: "manual",
+        signal: AbortSignal.timeout(remaining),
+        headers: {
+          Accept: "application/octet-stream",
+          "User-Agent": "aios-dashboard-installer",
+          // Never forward a GitHub credential to a release CDN (or any other
+          // origin). Signed MCP URLs carry their credential in the URL itself.
+          ...(token && sameOrigin ? { Authorization: `Bearer ${token}` } : {}),
+        },
+      });
+      if ([301, 302, 303, 307, 308].includes(response.status)) {
+        const location = response.headers.get("location");
+        if (!location) {
+          throw new Error(
+            `Download redirect had no location from ${redactSource(current.href)}`,
+          );
+        }
+        let next;
+        try {
+          next = new URL(location, current);
+        } catch {
+          throw new Error(
+            `Download returned an invalid redirect from ${redactSource(current.href)}.`,
+          );
+        }
+        if (sameOriginRedirectsOnly && next.origin !== original.origin) {
+          throw new Error(
+            `Dashboard source refused a redirect to a different origin (${next.origin}).`,
+          );
+        }
+        current = next;
+        continue;
+      }
+      if (!response.ok) {
+        throw new Error(
+          `Download failed (${response.status}) from ${redactSource(current.href)}`,
+        );
+      }
+      const declaredSize = Number(response.headers.get("content-length"));
+      if (Number.isFinite(declaredSize) && declaredSize > MAX_SOURCE_BYTES) {
+        await response.body?.cancel();
+        throw new Error(
+          `Dashboard source exceeds the ${MAX_SOURCE_BYTES} byte download limit (${redactSource(current.href)}).`,
+        );
+      }
+      if (!response.body)
+        throw new Error(
+          `Download returned no body from ${redactSource(current.href)}`,
+        );
+      const chunks = [];
+      let bytes = 0;
+      for await (const chunk of response.body) {
+        const buffer = Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > MAX_SOURCE_BYTES) {
+          throw new Error(
+            `Dashboard source exceeds the ${MAX_SOURCE_BYTES} byte download limit (${redactSource(current.href)}).`,
+          );
+        }
+        chunks.push(buffer);
+      }
+      return Buffer.concat(chunks, bytes);
+    } catch (error) {
+      if (
+        error?.name === "TimeoutError" ||
+        (error?.name === "AbortError" && Date.now() >= deadline)
+      ) {
+        throw new Error(
+          `Dashboard source download timed out after ${Math.ceil(timeoutMs / 1_000)} seconds (${redactSource(original.href)}).`,
+        );
+      }
+      throw error;
+    }
+  }
+  throw new Error(
+    `Too many redirects while downloading ${redactSource(original.href)}`,
+  );
+}
+
+export async function downloadSource({
+  version,
+  ref,
+  source,
+  sourceSha256,
+  env = process.env,
+}) {
+  if (source) {
+    if (!sourceSha256) {
+      throw new Error(
+        "--source requires --source-sha256 so the artifact can be verified.",
+      );
+    }
+    let buffer;
+    if (/^https?:\/\//i.test(source)) {
+      buffer = await fetchBuffer(source, { sameOriginRedirectsOnly: true });
+    } else if (source.startsWith("file:")) {
+      const file = fileURLToPath(source);
+      if ((await stat(file)).size > MAX_SOURCE_BYTES) {
+        throw new Error(
+          `Dashboard source exceeds the ${MAX_SOURCE_BYTES} byte download limit.`,
+        );
+      }
+      buffer = await readFile(file);
+    } else {
+      if ((await stat(source)).size > MAX_SOURCE_BYTES) {
+        throw new Error(
+          `Dashboard source exceeds the ${MAX_SOURCE_BYTES} byte download limit.`,
+        );
+      }
+      buffer = await readFile(source);
+    }
+    verifySourceSha256(buffer, sourceSha256);
+    return buffer;
+  }
+
+  const token = githubToken(env);
+  if (ref) {
+    try {
+      return await fetchBuffer(refZipUrl(ref), { token });
+    } catch (error) {
+      if (!token) throw error;
+      const api = `https://api.github.com/repos/${REPOSITORY}/zipball/${encodeURIComponent(ref)}`;
+      return fetchBuffer(api, { token });
+    }
+  }
+
+  if (token) {
+    const tag = `v${version}`;
+    const metadataResponse = await fetch(
+      `https://api.github.com/repos/${REPOSITORY}/releases/tags/${tag}`,
+      {
+        headers: {
+          Accept: "application/vnd.github+json",
+          Authorization: `Bearer ${token}`,
+          "User-Agent": "aios-dashboard-installer",
+          "X-GitHub-Api-Version": "2022-11-28",
+        },
+      },
+    );
+    if (metadataResponse.ok) {
+      const release = await metadataResponse.json();
+      const expected = `aios-dashboard-${version}.zip`;
+      const asset = release.assets?.find(
+        (candidate) => candidate.name === expected,
+      );
+      if (asset?.url) return fetchBuffer(asset.url, { token });
+    }
+  }
+  return fetchBuffer(releaseAssetUrl(version));
+}