aios-dashboard 0.2.0

package/lib/tunnel.mjs

@@ -0,0 +1,250 @@
+/**
+ * The HTTPS front door for a runner sitting on somebody's laptop.
+ *
+ * A hosted dashboard can only reach a runner over HTTPS, and a laptop has no
+ * public certificate. `cloudflared` solves that in one command and no account:
+ * a quick tunnel hands back a throwaway `https://…trycloudflare.com` origin
+ * that forwards to a local port.
+ *
+ * Three ways to get the binary, in the order that asks the member for least:
+ *
+ *  1. already on PATH, or in this CLI's data directory from a previous run;
+ *  2. the `cloudflared` npm package, if the workspace happens to have it;
+ *  3. downloaded once from Cloudflare's GitHub releases into the data dir.
+ *
+ * When all three fail the member is not stuck: `--tunnel-url` accepts an origin
+ * from any tunnel they already run (ngrok, a reverse proxy, a Tailscale funnel),
+ * and `connect` skips this file entirely.
+ */
+import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { createWriteStream, existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import path from "node:path";
+
+import {
+  cloudflaredAssetName,
+  dataDir,
+  findExecutableOrNull,
+  portableCommand,
+} from "./paths.mjs";
+import { findExecutable } from "./prerequisites.mjs";
+
+const RELEASE_BASE =
+  "https://github.com/cloudflare/cloudflared/releases/latest/download";
+
+export const QUICK_TUNNEL_PATTERN =
+  /https:\/\/[a-z0-9][a-z0-9-]*\.trycloudflare\.com/i;
+
+export function binaryName(platform = process.platform) {
+  return platform === "win32" ? "cloudflared.exe" : "cloudflared";
+}
+
+/** Where a downloaded binary is kept between runs. */
+export function cachedBinaryPath(platform = process.platform, env = process.env) {
+  return path.join(dataDir(platform, env), "bin", binaryName(platform));
+}
+
+/**
+ * Find cloudflared without downloading anything.
+ *
+ * Checked in this order because each step is cheaper and less surprising than
+ * the next: the member's own install wins over ours, and ours wins over
+ * fetching a fresh one.
+ */
+export function locateCloudflared({
+  env = process.env,
+  platform = process.platform,
+  exists = existsSync,
+} = {}) {
+  const onPath = findExecutable("cloudflared", { env, platform });
+  if (onPath) return { path: onPath, source: "path" };
+
+  const cached = cachedBinaryPath(platform, env);
+  if (exists(cached)) return { path: cached, source: "cache" };
+
+  // The npm package installs the binary next to itself; if a workspace has it
+  // as a dependency there is no reason to fetch a second copy.
+  const packaged = findExecutableOrNull(
+    path.join(process.cwd(), "node_modules", ".bin", binaryName(platform)),
+    exists,
+  );
+  if (packaged) return { path: packaged, source: "npm" };
+
+  return null;
+}
+
+export const CLOUDFLARED_MISSING = [
+  "cloudflared was not found and could not be downloaded.",
+  "",
+  "Either install it once:",
+  "  macOS    brew install cloudflared",
+  "  Linux    see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
+  "  npm      npm install -g cloudflared",
+  "",
+  "Or run your own tunnel and pass its address:",
+  "  aios-dashboard connect --tunnel-url https://runner.example.com",
+].join("\n");
+
+/**
+ * Fetch the binary for this machine into the data dir.
+ *
+ * Written to a temporary name and renamed, so an interrupted download never
+ * leaves a half-file that later runs would happily try to execute.
+ */
+export async function downloadCloudflared({
+  platform = process.platform,
+  arch = process.arch,
+  env = process.env,
+  log = console.log,
+} = {}) {
+  const asset = cloudflaredAssetName(platform, arch);
+  if (!asset) {
+    throw new Error(
+      `No cloudflared build is published for ${platform}/${arch}. Use --tunnel-url with your own tunnel.`,
+    );
+  }
+  const target = cachedBinaryPath(platform, env);
+  await mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.download-${process.pid}`;
+
+  log(`Downloading cloudflared for ${platform}/${arch} …`);
+  const response = await fetch(`${RELEASE_BASE}/${asset}`, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(180_000),
+  });
+  if (!response.ok || !response.body) {
+    throw new Error(`cloudflared download failed with HTTP ${response.status}.`);
+  }
+
+  if (asset.endsWith(".tgz")) {
+    // The macOS asset is a gzipped tar holding one file. Unpacking a single
+    // member is cheaper and more predictable than shelling out to tar.
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const { extractSingleFileTgz } = await import("./zip.mjs");
+    await writeFile(temporary, await extractSingleFileTgz(buffer));
+  } else {
+    await pipeline(response.body, createWriteStream(temporary));
+  }
+
+  await chmod(temporary, 0o755).catch(() => undefined);
+  await rename(temporary, target);
+  return target;
+}
+
+export async function ensureCloudflared({
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  allowDownload = true,
+  log = console.log,
+} = {}) {
+  const found = locateCloudflared({ env, platform });
+  if (found) return found;
+  if (!allowDownload) throw new Error(CLOUDFLARED_MISSING);
+  try {
+    const downloaded = await downloadCloudflared({ platform, arch, env, log });
+    return { path: downloaded, source: "download" };
+  } catch (error) {
+    throw new Error(
+      `${CLOUDFLARED_MISSING}\n\n(download error: ${error instanceof Error ? error.message : String(error)})`,
+    );
+  }
+}
+
+/** The cloudflared invocation for a quick tunnel or a member's named one. */
+export function tunnelArgs({ port, name, hostname: stableHostname }) {
+  if (name) {
+    const args = ["tunnel", "--url", `http://localhost:${port}`];
+    if (stableHostname) args.push("--hostname", stableHostname);
+    args.push("run", name);
+    return args;
+  }
+  return [
+    "tunnel",
+    "--no-autoupdate",
+    "--url",
+    `http://localhost:${port}`,
+  ];
+}
+
+/**
+ * Pull the public origin out of cloudflared's chatter.
+ *
+ * Quick tunnels announce the hostname on stderr inside a box of `|` characters,
+ * so this matches the URL anywhere in the stream rather than parsing lines. A
+ * named tunnel never announces one, which is why `--tunnel-name` also wants a
+ * hostname.
+ */
+export function originFromOutput(text) {
+  const match = String(text ?? "").match(QUICK_TUNNEL_PATTERN);
+  return match ? match[0] : null;
+}
+
+/**
+ * Start a tunnel and resolve once it has an origin.
+ *
+ * The child is returned alongside the origin so the caller owns its lifetime:
+ * `connect` keeps it, watches it, and restarts it if Cloudflare drops the
+ * quick tunnel — which they do, without warning, after a few hours.
+ */
+export function startTunnel({
+  binary,
+  port,
+  name = null,
+  hostname: stableHostname = null,
+  timeoutMs = 60_000,
+  onLine = () => {},
+}) {
+  const invocation = portableCommand(binary, tunnelArgs({ port, name, hostname: stableHostname }));
+  const child = spawn(invocation.command, invocation.args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+  });
+
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      reject(new Error("The tunnel did not report a public address in time."));
+    }, timeoutMs);
+
+    const finish = (origin) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ child, origin });
+    };
+
+    const read = (chunk) => {
+      const text = chunk.toString("utf8");
+      buffer = `${buffer}${text}`.slice(-8_000);
+      onLine(text);
+      if (stableHostname) {
+        finish(`https://${stableHostname}`);
+        return;
+      }
+      const origin = originFromOutput(buffer);
+      if (origin) finish(origin);
+    };
+
+    child.stdout?.on("data", read);
+    child.stderr?.on("data", read);
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.once("exit", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(new Error(`cloudflared exited with code ${code} before opening a tunnel.`));
+    });
+  });
+}

package/lib/zip.mjs

@@ -0,0 +1,277 @@
+import {
+  chmod,
+  copyFile,
+  cp,
+  mkdir,
+  readFile,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { gunzipSync, inflateRawSync } from "node:zlib";
+
+const EOCD = 0x06054b50;
+const CENTRAL_HEADER = 0x02014b50;
+const LOCAL_HEADER = 0x04034b50;
+const MAX_EOCD_SEARCH = 65_557;
+export const MAX_ZIP_ENTRIES = 20_000;
+export const MAX_ZIP_ENTRY_BYTES = 64 * 1024 * 1024;
+export const MAX_ZIP_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
+
+function findEocd(buffer) {
+  if (buffer.length < 22) {
+    throw new Error("Invalid ZIP: end-of-central-directory record not found.");
+  }
+  const start = Math.max(0, buffer.length - MAX_EOCD_SEARCH);
+  for (let offset = buffer.length - 22; offset >= start; offset -= 1) {
+    if (buffer.readUInt32LE(offset) === EOCD) return offset;
+  }
+  throw new Error("Invalid ZIP: end-of-central-directory record not found.");
+}
+
+function safeEntryPath(name) {
+  const normalized = name.replaceAll("\\", "/");
+  if (
+    !normalized ||
+    normalized.includes("\0") ||
+    normalized.startsWith("/") ||
+    /^[A-Za-z]:\//.test(normalized)
+  ) {
+    throw new Error(`Unsafe ZIP path: ${name}`);
+  }
+  const segments = normalized.split("/").filter(Boolean);
+  if (segments.some((segment) => segment === "..")) {
+    throw new Error(`Unsafe ZIP path: ${name}`);
+  }
+  return segments.join("/");
+}
+
+function within(root, target) {
+  const relative = path.relative(root, target);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+function decodeEntry(buffer, offset) {
+  if (offset < 0 || offset + 46 > buffer.length) {
+    throw new Error("Invalid ZIP: malformed central directory.");
+  }
+  if (buffer.readUInt32LE(offset) !== CENTRAL_HEADER) {
+    throw new Error("Invalid ZIP: malformed central directory.");
+  }
+  const flags = buffer.readUInt16LE(offset + 8);
+  const method = buffer.readUInt16LE(offset + 10);
+  const compressedSize = buffer.readUInt32LE(offset + 20);
+  const uncompressedSize = buffer.readUInt32LE(offset + 24);
+  const nameLength = buffer.readUInt16LE(offset + 28);
+  const extraLength = buffer.readUInt16LE(offset + 30);
+  const commentLength = buffer.readUInt16LE(offset + 32);
+  const externalAttributes = buffer.readUInt32LE(offset + 38);
+  const localOffset = buffer.readUInt32LE(offset + 42);
+  const nameStart = offset + 46;
+  const next = nameStart + nameLength + extraLength + commentLength;
+  if (next > buffer.length) {
+    throw new Error("Invalid ZIP: malformed central directory.");
+  }
+  const name = buffer
+    .subarray(nameStart, nameStart + nameLength)
+    .toString("utf8");
+  return {
+    flags,
+    method,
+    compressedSize,
+    uncompressedSize,
+    externalAttributes,
+    localOffset,
+    name,
+    next,
+  };
+}
+
+function compressedEntryData(buffer, entry) {
+  const offset = entry.localOffset;
+  if (offset < 0 || offset + 30 > buffer.length) {
+    throw new Error(`Invalid ZIP local header for ${entry.name}`);
+  }
+  if (buffer.readUInt32LE(offset) !== LOCAL_HEADER) {
+    throw new Error(`Invalid ZIP local header for ${entry.name}`);
+  }
+  const nameLength = buffer.readUInt16LE(offset + 26);
+  const extraLength = buffer.readUInt16LE(offset + 28);
+  const start = offset + 30 + nameLength + extraLength;
+  const end = start + entry.compressedSize;
+  if (start > buffer.length || end > buffer.length) {
+    throw new Error(`Invalid ZIP compressed data for ${entry.name}`);
+  }
+  return buffer.subarray(start, end);
+}
+
+function entryData(entry) {
+  const compressed = entry.compressed;
+  let data;
+  if (entry.method === 0) data = compressed;
+  else if (entry.method === 8) {
+    data = inflateRawSync(compressed, {
+      maxOutputLength: Math.max(1, entry.uncompressedSize),
+    });
+  } else throw new Error(`Unsupported ZIP compression method ${entry.method}.`);
+  if (data.length !== entry.uncompressedSize) {
+    throw new Error(`Invalid ZIP size for ${entry.name}`);
+  }
+  return data;
+}
+
+export async function extractZip(buffer, destination) {
+  const root = path.resolve(destination);
+  const eocd = findEocd(buffer);
+  const entryCount = buffer.readUInt16LE(eocd + 10);
+  if (entryCount > MAX_ZIP_ENTRIES) {
+    throw new Error(
+      `ZIP contains too many entries (limit ${MAX_ZIP_ENTRIES}).`,
+    );
+  }
+  const centralSize = buffer.readUInt32LE(eocd + 12);
+  let offset = buffer.readUInt32LE(eocd + 16);
+  const centralEnd = offset + centralSize;
+  if (offset > eocd || centralEnd > eocd || centralEnd < offset) {
+    throw new Error("Invalid ZIP: central directory is outside the archive.");
+  }
+  const entries = [];
+  let totalUncompressedBytes = 0;
+  for (let index = 0; index < entryCount; index += 1) {
+    const entry = decodeEntry(buffer, offset);
+    offset = entry.next;
+    if (offset > centralEnd) {
+      throw new Error("Invalid ZIP: malformed central directory size.");
+    }
+    if (entry.flags & 0x1) {
+      throw new Error("Encrypted ZIP entries are not supported.");
+    }
+    if (![0, 8].includes(entry.method)) {
+      throw new Error(`Unsupported ZIP compression method ${entry.method}.`);
+    }
+    if (entry.uncompressedSize > MAX_ZIP_ENTRY_BYTES) {
+      throw new Error(
+        `ZIP entry exceeds the ${MAX_ZIP_ENTRY_BYTES} byte uncompressed limit: ${entry.name}`,
+      );
+    }
+    totalUncompressedBytes += entry.uncompressedSize;
+    if (totalUncompressedBytes > MAX_ZIP_UNCOMPRESSED_BYTES) {
+      throw new Error(
+        `ZIP exceeds the ${MAX_ZIP_UNCOMPRESSED_BYTES} byte total uncompressed limit.`,
+      );
+    }
+    entries.push({
+      ...entry,
+      compressed: compressedEntryData(buffer, entry),
+    });
+  }
+  if (offset !== centralEnd) {
+    throw new Error(
+      "Invalid ZIP: central directory entry count does not match its size.",
+    );
+  }
+
+  await mkdir(root, { recursive: true });
+  const deferredLinks = [];
+
+  for (const entry of entries) {
+    const relative = safeEntryPath(entry.name);
+    if (!relative) continue;
+    const target = path.resolve(root, relative);
+    if (!within(root, target))
+      throw new Error(`Unsafe ZIP path: ${entry.name}`);
+    const mode = (entry.externalAttributes >>> 16) & 0xffff;
+    const fileType = mode & 0xf000;
+    const isDirectory = entry.name.endsWith("/") || fileType === 0x4000;
+    if (isDirectory) {
+      await mkdir(target, { recursive: true });
+      continue;
+    }
+
+    const data = entryData(entry);
+    await mkdir(path.dirname(target), { recursive: true });
+    if (fileType === 0xa000) {
+      deferredLinks.push({ target, link: data.toString("utf8") });
+      continue;
+    }
+    await writeFile(target, data);
+    if (mode & 0o111) await chmod(target, 0o755);
+  }
+
+  // GitHub source archives preserve Git symlinks. Dereference them into ordinary
+  // files/directories so the installed dashboard also works on Windows without
+  // Developer Mode or elevated symlink privileges.
+  for (const { target, link } of deferredLinks) {
+    const source = path.resolve(path.dirname(target), link);
+    if (!within(root, source)) throw new Error(`Unsafe ZIP symlink: ${link}`);
+    const sourceStat = await stat(source);
+    if (sourceStat.isDirectory()) await cp(source, target, { recursive: true });
+    else await copyFile(source, target);
+  }
+}
+
+export async function findSourceRoot(extracted) {
+  const candidates = [path.resolve(extracted)];
+  while (candidates.length > 0) {
+    const candidate = candidates.shift();
+    try {
+      const packageJson = JSON.parse(
+        await readFile(path.join(candidate, "package.json"), "utf8"),
+      );
+      if (
+        packageJson &&
+        (await stat(path.join(candidate, "app"))).isDirectory()
+      ) {
+        return candidate;
+      }
+    } catch {
+      // This directory is not the dashboard source root.
+    }
+    const relativeDepth = path
+      .relative(extracted, candidate)
+      .split(path.sep)
+      .filter(Boolean).length;
+    if (relativeDepth >= 2) continue;
+    const { readdir } = await import("node:fs/promises");
+    for (const entry of await readdir(candidate, { withFileTypes: true })) {
+      if (entry.isDirectory())
+        candidates.push(path.join(candidate, entry.name));
+    }
+  }
+  throw new Error(
+    "Downloaded archive does not contain an AIOS Dashboard source tree.",
+  );
+}
+
+/**
+ * Unpack the single file inside a gzipped tar.
+ *
+ * Cloudflare ships the macOS cloudflared build as a `.tgz` holding one
+ * executable. A full tar reader is not worth carrying for that, so this walks
+ * the 512-byte headers, finds the first regular file, and returns its bytes.
+ */
+export async function extractSingleFileTgz(buffer) {
+  const tar = gunzipSync(buffer);
+  let offset = 0;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/, "");
+    if (!name) break;
+    const sizeField = header
+      .subarray(124, 136)
+      .toString("utf8")
+      .replace(/[\0 ]+$/, "");
+    const size = Number.parseInt(sizeField || "0", 8);
+    if (!Number.isInteger(size) || size < 0) {
+      throw new Error("Unreadable tar header in the cloudflared archive.");
+    }
+    const type = header.subarray(156, 157).toString("utf8");
+    const start = offset + 512;
+    if (type === "0" || type === "\0") return tar.subarray(start, start + size);
+    offset = start + Math.ceil(size / 512) * 512;
+  }
+  throw new Error("The cloudflared archive contained no file.");
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "aios-dashboard",
+  "version": "0.2.0",
+  "description": "Install the AIOS Dashboard into an AIOS workspace.",
+  "keywords": [
+    "aios",
+    "dashboard",
+    "installer",
+    "local-first"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niknorf/aios-dashboard.git",
+    "directory": "cli"
+  },
+  "bin": {
+    "aios-dashboard": "bin/aios-dashboard.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22.22.0"
+  }
+}