Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

40.1 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import { Command } from "commander";
import { execFile, spawn } from "child_process";
import {
  existsSync,
  readFileSync,
  writeFileSync,
  unlinkSync,
  mkdirSync,
} from "fs";
import { join, dirname } from "path";
import { platform } from "os";
import { fileURLToPath } from "url";
import { createConnection } from "net";
import { resolveWorkspaceId } from "../bootstrap.js";
import { findWorkspaceForCwd, getDefaultWorkspace, getLocalToken, loadWorkspaces } from "../config.js";
import { detectSystem } from "../system.js";
import { createClient } from "../../client/factory.js";
import { ixHome } from "../ix-home.js";
import { ensureFreshMap } from "../map-freshness.js";

// The paths below are functions, not consts, so they follow IX_HOME as it is
// when a command runs rather than when this module was imported -- see
// `ixHome()`.
const pidFile = (): string => join(ixHome(), "compass.pid");
// Records the workspace scope (id, or "*all*") of the running visualizer, so a second
// `ix view` launched from a different workspace can warn instead of silently showing the
// already-running (differently-scoped) instance.
const scopeFile = (): string => join(ixHome(), "compass.scope");
const portFile = (): string => join(ixHome(), "compass.port");
/**
 * `.cjs`, not `.js`.
 *
 * The script this writes is CommonJS — it `require`s http, fs and path. A `.js`
 * file's module system is decided by the nearest `package.json` *above it*, so
 * with `IX_HOME` anywhere under a directory declaring `"type": "module"`, node
 * refuses the script with `require is not defined in ES module scope` and
 * `ix view` reports only "started … but is not yet serving", which names
 * neither the cause nor the fix. `.cjs` is CommonJS whatever any ancestor
 * says. (`$HOME/package.json` is rare but real — this box has one.)
 */
const serverScriptFile = (): string => join(ixHome(), "tmp", "compass-server.cjs");
const BACKEND_URL = "http://localhost:8090";

/** Resolve the compass dist directory — installed path first, then dev fallback. */
function findCompassDist(): string | null {
  // Installed: $IX_HOME/cli/compass/
  const installed = join(ixHome(), "cli", "compass");
  if (existsSync(join(installed, "index.html"))) return installed;

  // Dev / repo: relative to this file → ../../compass/dist/
  const thisDir = dirname(fileURLToPath(import.meta.url));
  const repoDist = join(thisDir, "..", "..", "..", "compass", "dist");
  if (existsSync(join(repoDist, "index.html"))) return repoDist;

  return null;
}

function removeCompassState(): void {
  for (const path of [pidFile(), scopeFile(), portFile()]) {
    try { unlinkSync(path); } catch { /* ignore */ }
  }
}

function parsePort(value: string): number | null {
  const port = Number(value.trim());
  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
}

/**
 * Read a file, keeping "not there" and "there but unreadable" apart.
 *
 * Collapsing both to null is the tempting shape and the wrong one. An
 * unreadable compass.pid — a directory left by a botched extract, a root-owned
 * file after one `sudo ix` — would read as "no visualizer running", and the
 * callers act on that: one deletes a live server's state files, the other goes
 * on to spawn a second server it then cannot record or stop. Only ENOENT means
 * absent. Anything else is a real problem and belongs to the caller.
 *
 * Reading straight out instead of checking existsSync first is what closes
 * CodeQL js/file-system-race: the check could always go stale before the read,
 * and it never told us the read would succeed anyway.
 */
function readTextIfPresent(path: string): string | null {
  try {
    return readFileSync(path, "utf-8");
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw err;
  }
}

/**
 * Read the persisted port, falling back to the server script written by older releases.
 *
 * Unlike the PID and scope reads, this one does swallow an unreadable file: it
 * is a best-effort lookup for a URL to print, not a liveness check, so a corrupt
 * compass.port should degrade to the legacy script rather than fail the command.
 * That was already the behaviour; only the existsSync guards are gone.
 */
function readRunningPort(): number | null {
  try {
    const raw = readTextIfPresent(portFile());
    const port = raw === null ? null : parsePort(raw);
    if (port !== null) return port;
  } catch {
    // Fall through to the legacy server script.
  }

  try {
    const match = readTextIfPresent(serverScriptFile())?.match(/^const PORT = (\d+);$/m);
    const port = match?.[1] ? parsePort(match[1]) : null;
    if (port !== null) {
      // Best-effort migration for a visualizer started before compass.port existed.
      try { writeFileSync(portFile(), String(port)); } catch { /* ignore */ }
    }
    return port;
  } catch {
    return null;
  }
}

/**
 * What to print under "already running", given where it is actually serving.
 *
 * #358 made this branch report the running port instead of echoing back the one
 * just requested, which fixed the unreachable URL. It stayed silent about the
 * request itself though, so `ix view -p 19124` against a server on 19123 prints
 * a correct URL for a port you did not ask for and never says the flag was
 * ignored — you find out by noticing the number changed.
 *
 * Pure, because the decision is all this is, and inline in a command action it
 * could only be exercised by launching a detached server.
 *
 * `token` is threaded rather than read from `CACHE_BUST` so this stays pure.
 * The URL it prints carries the bust for a reason: `ix upgrade` replaces the
 * dist in place and leaves the server running, so the next `ix view` lands
 * here, prints a URL and opens nothing. That is the reporter's exact path, and
 * a bust that only covered the opened tab would miss it.
 */
export function runningInstanceLines(
  runningPort: number | null,
  requestedPort: number,
  portWasRequested: boolean,
  token: string = CACHE_BUST,
): string[] {
  if (runningPort === null) {
    return [
      "[!] The running visualizer's port is unknown.",
      "    Run 'ix view stop' then 'ix view' to restart it.",
    ];
  }

  const lines = [`  ${browserUrl(`http://localhost:${runningPort}`, token)}`];
  if (portWasRequested && runningPort !== requestedPort) {
    lines.push(`[!] You asked for port ${requestedPort}, but it is serving on ${runningPort}.`);
    lines.push(`    Run 'ix view stop' then 'ix view -p ${requestedPort}' to move it.`);
  }
  return lines;
}

/**
 * Read PID from file and check if the process is alive.
 *
 * An unreadable PID file throws rather than reporting "not running". Both
 * callers treat null as licence to act — `stop` wipes the state files, `start`
 * launches a detached server — so answering null for a file we simply could not
 * read would delete a live server's only record, or orphan a fresh one.
 */
function readAlivePid(): number | null {
  const raw = readTextIfPresent(pidFile());
  if (raw === null) {
    removeCompassState();
    return null;
  }
  const pid = Number(raw.trim());
  if (!Number.isInteger(pid) || pid <= 0) {
    removeCompassState();
    return null;
  }
  try {
    process.kill(pid, 0); // signal 0 = existence check
    return pid;
  } catch {
    // Stale PID file
    removeCompassState();
    return null;
  }
}

/**
 * Does `port` answer like this visualizer? An unknown `/__ix/` route gets the
 * server's own JSON 404, which nothing else on a port is likely to send. Used
 * before acting on the PID file: a PID outlives its process and can be reused
 * by an unrelated one, which `stop` would otherwise SIGTERM.
 */
export async function isVisualizerOnPort(port: number, timeoutMs = 1500): Promise<boolean> {
  try {
    const res = await fetch(`http://127.0.0.1:${port}/__ix/ping`, { signal: AbortSignal.timeout(timeoutMs) });
    if (res.status !== 404) return false;
    const body = (await res.json()) as { ok?: unknown; error?: unknown };
    return body.ok === false && typeof body.error === "string" && body.error.startsWith("not found: /__ix/ping");
  } catch {
    return false;
  }
}

/** Check whether a port is already in use. */
function isPortInUse(port: number): Promise<boolean> {
  return new Promise((resolve) => {
    const conn = createConnection({ port, host: "127.0.0.1" });
    conn.on("connect", () => {
      conn.end();
      resolve(true);
    });
    conn.on("error", () => resolve(false));
  });
}

/**
 * Wait for the detached server to accept connections.
 *
 * It is spawned with `stdio: "ignore"`, so anything it writes on the way down
 * goes nowhere — including the throw that now guards its argument contract.
 * Without this the CLI printed "[ok] Visualizer started", wrote a PID file for
 * a dead process and opened a browser on a closed port.
 *
 * Polls rather than watching for `exit`: the child is detached and unref'd, and
 * the question worth answering is whether the port is actually serving, not
 * whether the process happens to still be alive.
 */
async function waitForServer(port: number, timeoutMs = 8000): Promise<boolean> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    if (await isPortInUse(port)) return true;
    await new Promise((r) => setTimeout(r, 100));
  }
  return false;
}

/**
 * Path to the CLI entry point of the install generating this script.
 *
 * Taken from this module's own location rather than derived from the compass
 * dist directory, so it holds for a repo checkout as well as an install.
 */
function cliMainForScript(): string {
  return join(dirname(fileURLToPath(import.meta.url)), "..", "main.js");
}

/** Build the argv payload shared by the production launcher and server tests. */
export function serverRuntimeArgs(
  distDir: string,
  port: number,
  workspaceId: string | null,
  systemId: string | null,
  mapRoot: string | null,
  cliMainPath: string = cliMainForScript(),
): string[] {
  return [
    distDir,
    String(port),
    workspaceId ?? "",
    systemId ?? "",
    mapRoot ?? "",
    cliMainPath,
  ];
}

/**
 * Generate the invariant server script that serves static files + proxies /v1.
 *
 * Runtime values are supplied as argv when the script is spawned. In
 * particular, SYSTEM_ID may come from the backend, so embedding it here would
 * create a network-data-to-executable-file path even though JSON.stringify
 * made the generated JavaScript syntactically safe.
 */
export function serverScript(): string {
  return `
const http = require("http");
const fs = require("fs");
const path = require("path");
const url = require("url");
const { execFile } = require("child_process");

const DIST = process.argv[2];
const PORT = Number(process.argv[3]);
// How long to wait on the backend before answering 504. Generous, because it
// must not fire on a legitimately slow read: /v1/map rebuilds the whole map on
// every call and has been measured at 276s on a large graph. Overridable only
// under NODE_ENV=test, like the seams below, so a shipped install cannot be
// given a short timeout through the environment — and so the timeout itself
// can be tested without a ten-minute test.
const PROXY_TIMEOUT_MS = (process.env.NODE_ENV === "test" && process.env.IX_VIEW_PROXY_TIMEOUT_MS)
  ? Number(process.env.IX_VIEW_PROXY_TIMEOUT_MS)
  : 600000;

const BACKEND = (process.env.NODE_ENV === "test" && process.env.IX_VIEW_BACKEND_URL)
  ? process.env.IX_VIEW_BACKEND_URL
  : ${JSON.stringify(BACKEND_URL)};
const WORKSPACE_ID = process.argv[4] || null;
const SYSTEM_ID = process.argv[5] || null;

// The workspace root /__ix/remap maps, resolved by ix view start rather than
// re-derived here — empty/null when --all left the view unscoped.
const MAP_ROOT = process.argv[6] || null;

// The CLI that generated this script, resolved from its own location at
// launch time. Deriving it here from DIST only worked for the installed
// layout; findCompassDist's dev branch returns a repo path, from which the
// same arithmetic lands on a file that never exists.
//
// The env override is a test seam and is honoured only under NODE_ENV=test, so
// a shipped install cannot be pointed at an arbitrary script through the
// environment.
const MAP_MAIN = (process.env.NODE_ENV === "test" && process.env.IX_VIEW_MAP_MAIN)
  ? process.env.IX_VIEW_MAP_MAIN
  : process.argv[7];

if (!DIST || !Number.isInteger(PORT) || PORT < 1 || PORT > 65535 || !MAP_MAIN) {
  throw new Error("invalid ix view server arguments");
}

// One map at a time. execFile is asynchronous, so nothing else serialises them.
let mapInFlight = null;

const MIME = {
  ".html": "text/html",
  ".js":   "application/javascript",
  ".mjs":  "application/javascript",
  ".css":  "text/css",
  ".json": "application/json",
  ".png":  "image/png",
  ".jpg":  "image/jpeg",
  ".svg":  "image/svg+xml",
  ".ico":  "image/x-icon",
  ".woff": "font/woff",
  ".woff2":"font/woff2",
  ".ttf":  "font/ttf",
  ".map":  "application/json",
};

// ── Cache policy ────────────────────────────────────────────────────────────
//
// Sending no cache headers is not the same as sending "do not cache": with no
// Cache-Control, no ETag and no Last-Modified, a browser picks its own freshness
// heuristic and may reuse a response without ever asking. This server always
// serves 127.0.0.1 on a port it reuses, so that cache outlives an upgrade -- the
// old index.html comes back, names the old content-hashed bundles, and the
// entire previous Compass runs while /.version, fetched separately, reports the
// new build. The result is a status bar that says the fix shipped while the
// screen shows the build before it.
//
// The decision is keyed on the file about to be sent, never on the URL that
// asked for it. Those are not the same path: the SPA fallback rewrites filePath
// to index.html for any extensionless miss, so GET /assets/anything answers with
// index.html -- and deciding from the URL would stamp the entry point
// "immutable" for a year under an /assets/ key, which is the permanent form of
// the bug this exists to prevent.
//
// A content hash in the name is what makes "keep this forever" safe: the name
// changes whenever the bytes do. Sitting under assets/ is not the same claim.
// Compass is built in another repo, so nothing here can verify what it puts
// there, and one stable name -- a hand-placed file, a build whose
// assetFileNames drops [hash] -- would be pinned in a user's browser for a year
// against a fixed origin, with no revalidation path and no recovery short of
// clearing site data. So the guard checks for the hash it is asserting. The
// charset excludes the dash on purpose: a hash containing one simply misses
// the optimisation and is revalidated, while my-long-name.css matching would
// be the unrecoverable direction.
//
// No backslash escapes and no backticks anywhere in this block: the whole
// script is emitted from a template literal, so an escape is eaten before it
// reaches the generated file and a backtick ends the literal outright. Both
// were tried here; the second took the server down. Hence a bracketed dot
// rather than an escaped one, path.sep rather than a literal separator, and
// no backticks even inside these comments -- one here ends the literal just
// as surely as one in the code, which is how this block first failed to parse.
const DIST_ROOT = path.resolve(DIST);
const ASSET_PREFIX = path.join(DIST_ROOT, "assets") + path.sep;
const FINGERPRINTED = /-[A-Za-z0-9_]{8,}[.]/;
const cacheControl = (f) =>
  f.startsWith(ASSET_PREFIX) && FINGERPRINTED.test(path.basename(f))
    ? "public, max-age=31536000, immutable"
    : "no-store";

// The backend token, passed in the environment rather than argv so other local
// users cannot read it from the process list. Empty until the CLI has one.
const BACKEND_TOKEN = process.env.IX_VIEW_BACKEND_TOKEN || "";

const isLoopbackName = (h) => h === "localhost" || h === "127.0.0.1" || h === "[::1]";

// Loopback-only, for every request: the /v1 proxy forwards to a backend that
// can reset the graph, /__ix/remap shells out with the user's privileges, and
// static files are the user's. Rejects a foreign Host (DNS rebinding), an
// Origin other than this server's own (CSRF from any other site, including
// another localhost port: a simple POST needs no preflight) and a request the
// browser marks cross-site. Browsers send Origin on cross-site POSTs; curl and
// same-origin reads either omit it or send this server's own. The Origin is
// parsed with the URL API rather than a regex because this snippet lives
// inside a template literal and regex backslashes would be consumed every time
// the server is regenerated by ix view start.
function forbiddenReason(req) {
  // Strip the port, keeping a bracketed IPv6 literal intact ([::1]:8080 -> [::1]).
  let host = (req.headers.host || "").toLowerCase();
  host = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.split(":")[0];
  if (!isLoopbackName(host)) return "host";
  const origin = req.headers.origin;
  if (origin) {
    try {
      const u = new URL(origin);
      const own = (u.protocol === "http:" || u.protocol === "https:") &&
        isLoopbackName(u.hostname) && u.port === String(PORT);
      if (!own) return "origin";
    } catch {
      return "origin";
    }
  }
  if (String(req.headers["sec-fetch-site"] || "").toLowerCase() === "cross-site") return "cross-site";
  return null;
}

const server = http.createServer((req, res) => {
  const parsed = url.parse(req.url);
  const pathname = parsed.pathname || "/";

  if (forbiddenReason(req)) {
    req.resume();
    res.writeHead(403, { "Content-Type": "application/json", "Cache-Control": "no-store" });
    res.end(JSON.stringify({ ok: false, error: "forbidden: loopback only" }));
    return;
  }

  // Proxy /v1 requests to backend
  if (pathname.startsWith("/v1")) {
    // The path the backend will actually be asked for: the URL API resolves
    // dot segments, encoded ones included, exactly as the request will. Only
    // /v1 is proxied, so /v1/../x or /v1x never reaches another backend route
    // carrying this server's token.
    const target = new URL(pathname + (parsed.search || ""), BACKEND);
    if (target.pathname !== "/v1" && !target.pathname.startsWith("/v1/")) {
      req.resume();
      res.writeHead(404, { "Content-Type": "application/json", "Cache-Control": "no-store" });
      res.end(JSON.stringify({ ok: false, error: "not found: " + pathname }));
      return;
    }
    const backendUrl = target.href;
    const proxyHeaders = { ...req.headers, host: "localhost:8090" };
    // The backend authenticates this server, not the browser: never forward a
    // caller's own credentials or origin, and add the token when there is one.
    delete proxyHeaders.authorization;
    delete proxyHeaders.origin;
    if (BACKEND_TOKEN) proxyHeaders.authorization = "Bearer " + BACKEND_TOKEN;
    // Scope every proxied read to the workspace ix view was launched in, so the
    // System Compass visualiser isolates by workspace without the browser app
    // knowing anything about workspaces. The backend reads X-Ix-Workspace as a
    // fallback when no explicit workspace_id is on the request.
    if (WORKSPACE_ID) proxyHeaders["x-ix-workspace"] = WORKSPACE_ID;
    // When the launch directory is a multi-repo system, scope by system instead.
    // Co-ingest stores each member repo under its own workspace_id plus a shared
    // system_id, so a workspace-only scope (the parent dir's path-id) matches no
    // member nodes and Compass renders empty. X-Ix-System unions every member's
    // nodes plus the cross-repo edges; the backend (SystemScope) gives it
    // precedence over the workspace scope, so sending both is safe.
    if (SYSTEM_ID) proxyHeaders["x-ix-system"] = SYSTEM_ID;
    const proxyReq = http.request(backendUrl, {
      method: req.method,
      headers: proxyHeaders,
    }, (proxyRes) => {
      res.writeHead(proxyRes.statusCode, proxyRes.headers);
      proxyRes.pipe(res);
    });
    // A backend that accepts the socket and then never answers used to hang
    // here for ever: node puts no timeout on an outgoing request, so the
    // browser waited indefinitely, Compass recorded neither a result nor a
    // failure, and the region sat at "loading …" with nothing to distinguish a
    // slow map from a dead one. Answering 504 turns that into a state the
    // client can render and a user can act on.
    //
    // Generous, because it must not fire on a legitimately slow read: /v1/map
    // rebuilds the whole map on every call and has been measured at 276s on a
    // large graph. This is the point past which silence is a fault rather than
    // patience.
    proxyReq.setTimeout(PROXY_TIMEOUT_MS, () => {
      proxyReq.destroy(new Error("backend timed out"));
    });
    proxyReq.on("error", (err) => {
      // Whatever went wrong, the client is still waiting; say something.
      if (res.headersSent) { res.destroy(); return; }
      const timedOut = err && err.message === "backend timed out";
      res.writeHead(timedOut ? 504 : 502, { "Content-Type": "text/plain" });
      res.end(timedOut ? "Backend timed out" : "Backend unavailable");
    });
    req.pipe(proxyReq);
    return;
  }

  // Real /__ix/remap - rebuild the code map for the workspace this visualizer
  // was launched from (its cwd), by running the CLI's map command against it. The
  // stock endpoint was a stub that returned the SPA HTML. Loopback-only, like
  // every route: forbiddenReason has already run.
  if (pathname === "/__ix/remap" && req.method === "POST") {
    // Nothing reads the request body, but leaving it unconsumed holds the
    // stream open for the whole map.
    req.resume();
    // MAP_ROOT is the workspace this visualizer is showing, resolved once by
    // ix view start and supplied at launch. Mapping process.cwd() instead would
    // follow
    // whatever directory the detached server was launched from: --all does not
    // require that to be a workspace at all, so "ix view start --all" run from
    // a home directory turned one click into an ingest of the whole of it.
    if (!MAP_ROOT) {
      res.writeHead(409, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ ok: false, error: "remap needs a single workspace; this view was started with --all" }));
      return;
    }
    if (mapInFlight) {
      // execFile is async, so without this every POST starts another full
      // ingest and Louvain pass over the same workspace.
      res.writeHead(409, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ ok: false, error: "a remap is already running" }));
      return;
    }
    if (!fs.existsSync(MAP_MAIN)) {
      res.writeHead(500, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ ok: false, error: "ix CLI not found at " + MAP_MAIN }));
      return;
    }
    // --silent because nothing here reads stdout, and the default text render
    // is work done only to be thrown away. --remap because this is the Remap
    // button: it must recompute the map even when the server inherited
    // IX_AUTO_MAP=1, under which a stale map would be served as is (CL-13).
    // maxBuffer is raised anyway: the
    // default 1 MiB makes Node SIGTERM the child mid-map, which surfaces as a
    // 500 rather than as the truncation it is.
    const child = execFile(process.execPath, [MAP_MAIN, "map", MAP_ROOT, "--silent", "--remap"], { cwd: MAP_ROOT, timeout: 1800000, maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
      mapInFlight = null;
      if (res.destroyed) return; // client disconnected while mapping
      res.writeHead(err ? 500 : 200, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ ok: !err, error: err ? String(stderr || err.message).slice(0, 400) : undefined }));
    });
    mapInFlight = child;
    // Stop the map if the client goes away before we respond. res "close" fires
    // on abnormal teardown too; writableEnded tells normal completion apart
    // from a disconnect (IncomingMessage "close" can fire on request completion
    // in some Node versions, which would kill the map mid-flight).
    //
    // Killing mid-map is safe: the ingest baseline is only persisted after a
    // clean run, so an interrupted map re-ingests next time rather than
    // recording files as done that never landed.
    res.on("close", () => { if (!res.writableEnded) { try { child.kill(); } catch {} } });
    return;
  }

  // Unknown /__ix/* routes — return 404 with JSON, not SPA HTML.
  // Without this, /__ix/read, /__ix/explain, /__ix/inventory and /__ix/help
  // fall through to the static handler, which serves index.html. The client
  // tries to JSON.parse the HTML, gets an error, catches it silently, and
  // the user sees nothing. A 404 makes the failure detectable. (#473)
  if (pathname.startsWith("/__ix/")) {
    res.writeHead(404, { "Content-Type": "application/json", "Cache-Control": "no-store" });
    res.end(JSON.stringify({ ok: false, error: "not found: " + pathname }));
    return;
  }

  // Serve static files.
  let filePath = path.resolve(path.join(DIST, pathname === "/" ? "index.html" : pathname));

  // Everything served comes from inside DIST. url.parse does not normalise
  // a dot-dot segment, and path.join resolves straight out of the tree, so
  // without this GET /../../../../etc/passwd is read and returned 200. A
  // browser normalises dot-dot before sending, so the exposure is to other local
  // processes reading files as the user who ran the CLI rather than as
  // themselves -- which is still a file read this server has no business
  // doing. Checked before the SPA fallback, because an escaping path that
  // happens to exist never reaches it.
  if (filePath !== DIST_ROOT && !filePath.startsWith(DIST_ROOT + path.sep)) {
    res.writeHead(404, { "Content-Type": "text/plain", "Cache-Control": "no-store" });
    res.end("Not found");
    return;
  }

  // SPA fallback: if file doesn't exist and no extension, serve index.html
  if (!fs.existsSync(filePath) && !path.extname(filePath)) {
    filePath = path.join(DIST, "index.html");
  }

  fs.readFile(filePath, (err, data) => {
    if (err) {
      // SPA fallback for all 404s
      fs.readFile(path.join(DIST, "index.html"), (err2, fallback) => {
        if (err2) {
          res.writeHead(404, { "Content-Type": "text/plain" });
          res.end("Not found");
          return;
        }
        res.writeHead(200, {
          "Content-Type": "text/html",
          "Cache-Control": "no-store",
        });
        res.end(fallback);
      });
      return;
    }
    const ext = path.extname(filePath).toLowerCase();
    const mime = MIME[ext] || "application/octet-stream";
    res.writeHead(200, {
      "Content-Type": mime,
      "Cache-Control": cacheControl(filePath),
    });
    res.end(data);
  });
});

server.listen(PORT, "127.0.0.1", () => {
  // Server ready — parent already detached
});
`;
}

/**
 * One cache-bust token per CLI invocation.
 *
 * Base-36 milliseconds: short, URL-safe, and made here rather than read from
 * anywhere, so nothing on disk reaches the shell `openBrowser` runs.
 */
const CACHE_BUST = Date.now().toString(36);

/**
 * The visualizer URL, with the cache-bust token.
 *
 * `Cache-Control: no-store` only reaches a response the browser actually asks
 * for. The client that reported this cached `/` before the upgrade, so it never
 * asks — its entry is still fresh, it keeps serving the old index.html naming
 * the old hashed bundles, and it never learns the policy changed. `ix view`
 * reuses 127.0.0.1 on the same port across upgrades, so that entry outlives the
 * install meant to replace it. Without a different key the header is
 * prospective only: it protects the next upgrade, not the one the user just
 * ran, which is the one they are looking at.
 *
 * Every URL the CLI names goes through this, not just the one it opens. The
 * reporter's path is `ix upgrade` (which replaces the dist in place and leaves
 * the server running) then `ix view`, which takes the already-running branch
 * and only *prints* a URL; a bust on the opened tab alone would miss it
 * entirely, along with `--no-open`, a copied URL and a bookmark.
 *
 * Per invocation rather than keyed on the build stamp. The entry point is
 * `no-store` now, so there is no cache entry a repeat start could have hit and
 * nothing is lost by changing the key every time — while a stamp would have to
 * be read from the dist, which is absent in a dev build, exactly where an
 * iterating developer needs this most. Assets keep their own URLs, so they
 * still come from cache.
 */
export function browserUrl(serverUrl: string, token: string = CACHE_BUST): string {
  return `${serverUrl}/?ix=${token}`;
}

/**
 * The opener command for this platform, as a program and its arguments: no
 * shell ever parses the URL. Windows uses explorer.exe rather than cmd's
 * `start`, which would hand the URL to cmd's parser again.
 */
export function browserOpener(url: string, plat: NodeJS.Platform = platform()): [string, string[]] {
  if (plat === "darwin") return ["open", [url]];
  if (plat === "win32") return ["explorer.exe", [url]];
  return ["xdg-open", [url]];
}

function openBrowser(url: string): void {
  const [cmd, args] = browserOpener(url);
  // Non-critical: a missing opener just leaves the printed URL.
  execFile(cmd, args, { windowsHide: true }, () => {});
}

/**
 * The token the visualizer's /v1 proxy sends to the backend: IX_TOKEN, else
 * the stored local token, and only when that backend is on this machine.
 * Handed to the server through its environment, never argv.
 */
function viewBackendToken(): string {
  return getLocalToken(BACKEND_URL) ?? "";
}

export function registerViewCommand(program: Command): void {
  const view = program
    .command("view")
    .description("Open the Ix System Compass visualizer")
    .option("-p, --port <port>", "Port to serve on", "8080");

  view
    .command("start", { isDefault: true })
    .description("Start the visualizer (default)")
    .option("--no-open", "Don't auto-open browser")
    .option("--all", "Show every ingested workspace together (no workspace scoping)")
    .action(async (opts) => {
      const port = parseInt(view.opts().port, 10);
      if (isNaN(port) || port < 1 || port > 65535) {
        console.error("[error] Invalid port number.");
        process.exit(1);
      }
      // Whether -p was typed, not whether it differs from 8080. Comparing against
      // the default instead would stay silent for someone who explicitly passed
      // `-p 8080` to a server running elsewhere — the exact case they typed the
      // flag to find out about — and would nag anyone who typed nothing.
      const portWasRequested = view.getOptionValueSource("port") === "cli";

      // Resolve the workspace this visualizer is scoped to. The proxy stamps it as
      // X-Ix-Workspace on every /v1 call so Compass isolates by workspace without any
      // workspace awareness of its own. --all opts out (show the whole backend).
      const workspaceId = opts.all ? null : (resolveWorkspaceId() ?? null);
      // Resolved the same way workspaceId is, so /__ix/remap re-maps exactly
      // what the visualizer is showing. Null under --all, which deliberately
      // scopes to nothing — there is no single workspace to rebuild.
      const mapRoot = opts.all
        ? null
        : ((findWorkspaceForCwd(process.cwd()) ?? getDefaultWorkspace())?.root_path ?? null);

      // If the launch directory is a multi-repo system, scope by system_id instead of
      // workspace_id: co-ingested member repos live under their own workspace_ids, so a
      // workspace-only scope finds nothing (this is the "Compass not connected" bug).
      // Mirror `ix map`: detectSystem finds a locally co-ingested system; a repo the
      // stitcher joined into a system has no local marker, so fall back to the backend
      // lookup. --all opts out of all scoping.
      let systemId: string | null = null;
      if (!opts.all) {
        systemId = detectSystem(process.cwd())?.systemId ?? null;
        if (!systemId && workspaceId) {
          try {
            const looked = await createClient().workspaceSystem(workspaceId);
            systemId = looked.systemId ?? null;
          } catch {
            // Older backend without the stitch endpoint, or backend down — fall back to
            // workspace scoping (single-repo behavior is unaffected).
          }
        }
        // The system id (from a local marker or the backend) becomes a proxy
        // header and persisted scope label, so constrain it to the known id
        // charset before either use.
        if (systemId !== null && !/^[A-Za-z0-9_.:-]+$/.test(systemId)) {
          systemId = null;
        }
      }
      const workspaceName = workspaceId
        ? (findWorkspaceForCwd(process.cwd())?.workspace_name ?? workspaceId)
        : null;
      // A system scope takes precedence (it's what the proxy sends), so it also keys the
      // running-instance scope so launching from a member repo rescopes correctly.
      const scopeKey = systemId ? `system:${systemId}` : (workspaceId ?? "*all*");
      const scopeLabel = systemId
        ? `system "${systemId}"`
        : (workspaceName ? `workspace "${workspaceName}"` : "all workspaces");

      // An `ix map` after an edit may have left the map for whatever reads
      // regions next (CL-13); the visualizer shows them. Not under --all,
      // which has no one workspace to refresh. Never throws.
      if (!opts.all) await ensureFreshMap(mapRoot ? { root: mapRoot } : {});

      const existing = readAlivePid();
      if (existing) {
        console.log(`[ok] Visualizer is already running (PID ${existing})`);
        for (const line of runningInstanceLines(readRunningPort(), port, portWasRequested)) {
          console.log(line);
        }
        // The running instance has a fixed scope (baked at launch). If this directory
        // maps to a different workspace, say so rather than silently showing the old one.
        // Unreadable must not read as "no scope": that would skip the check
        // below and quietly hand back another workspace's graph, which is the
        // exact confusion the scope file exists to prevent. Empty counts as
        // unknown too, not as a scope literally named "".
        const runningKey = readTextIfPresent(scopeFile())?.trim() || null;
        if (runningKey !== null && runningKey !== scopeKey) {
          const runningLabel = runningKey === "*all*"
            ? "all workspaces"
            : `workspace "${loadWorkspaces().find(w => w.workspace_id === runningKey)?.workspace_name ?? runningKey}"`;
          console.log(`[!] It is scoped to ${runningLabel}, but this directory maps to ${scopeLabel}.`);
          console.log(`    Run 'ix view stop' then 'ix view' here to rescope.`);
        }
        return;
      }

      // Check if the port is already in use before attempting to start
      if (await isPortInUse(port)) {
        console.error(`[error] Port ${port} is already in use.`);
        console.error(`  Use -p <port> to specify a different port.`);
        process.exit(1);
      }

      const distDir = findCompassDist();
      if (!distDir) {
        console.error("[error] Compass UI not found.");
        console.error("  Expected at: $IX_HOME/cli/compass/ (installed)");
        console.error("  or: <repo>/compass/dist/ (development)");
        console.error("");
        // Releases v0.7.0-v0.8.1 shipped an empty compass/ directory, so for
        // most users the bundle is genuinely absent rather than misplaced.
        // `ix upgrade` fetches it from ix-compass-dist and repairs the install.
        console.error("  Fetch it with:  ix upgrade");
        console.error("");
        console.error("  The visualizer normally ships inside the Ix release tarball.");
        console.error("  If 'ix upgrade' does not resolve it, please report the issue at");
        console.error("  https://github.com/ix-infrastructure/Ix/issues");
        process.exit(1);
      }

      // Write server script to temp location
      const scriptDir = dirname(serverScriptFile());
      mkdirSync(scriptDir, { recursive: true });
      // The file is deliberately invariant: systemId can be returned by the
      // backend and must never flow into JavaScript that is written and then
      // executed. Runtime values travel as argv instead.
      writeFileSync(serverScriptFile(), serverScript());

      // Spawn detached process
      const child = spawn(process.execPath, [
        serverScriptFile(),
        ...serverRuntimeArgs(distDir, port, workspaceId, systemId, mapRoot),
      ], {
        detached: true,
        stdio: "ignore",
        env: { ...process.env, IX_VIEW_BACKEND_TOKEN: viewBackendToken() },
      });
      child.unref();

      if (!child.pid) {
        console.error("[error] Failed to start visualizer server.");
        process.exit(1);
      }

      // A pid only means the spawn succeeded — see waitForServer.
      const ready = await waitForServer(port);

      // Save PID, scope, and port for subsequent start/status/stop commands.
      mkdirSync(dirname(pidFile()), { recursive: true });
      writeFileSync(pidFile(), String(child.pid));
      writeFileSync(scopeFile(), scopeKey);
      writeFileSync(portFile(), String(port));

      // One URL, printed and opened. They used to differ: only the opened
      // one carried the cache bust, so --no-open, a copied URL, a bookmark
      // and the not-ready branch below all still resolved to the entry the
      // browser cached before the upgrade.
      const url = browserUrl(`http://localhost:${port}`);

      // Reported rather than fatal: the wait is a heuristic, and a machine slow
      // enough to exceed it would otherwise have a working visualizer killed off
      // or the command fail. The PID/scope/port files are written either way, so
      // `ix view status` and `ix view stop` still work on whatever did start.
      if (!ready) {
        console.error(`[!] Visualizer started (PID ${child.pid}) but is not yet serving ${url}.`);
        console.error("    If it does not come up shortly, run 'ix view stop', then");
        console.error("    'ix upgrade' if the Compass bundle is missing or incomplete.");
        return;
      }

      console.log(`[ok] Visualizer started (PID ${child.pid})`);
      console.log(`  ${url}`);
      console.log(
        systemId
          ? `  scope: ${scopeLabel}`
          : workspaceName
            ? `  scope: workspace "${workspaceName}"`
            : `  scope: all workspaces${opts.all ? " (--all)" : ""}`
      );

      if (opts.open !== false) {
        openBrowser(url);
      }
    });

  view
    .command("stop")
    .description("Stop the visualizer")
    .action(async () => {
      const pid = readAlivePid();
      if (!pid) {
        console.log("[ok] Visualizer is not running.");
        return;
      }
      // Only signal a PID that is still the visualizer. An instance started
      // before the port was recorded has nothing to check against and keeps
      // the old behaviour.
      const port = readRunningPort();
      if (port !== null && !(await isVisualizerOnPort(port))) {
        removeCompassState();
        console.log(`[ok] Visualizer is not running (PID ${pid} now belongs to another process; left alone).`);
        return;
      }

      try {
        process.kill(pid, "SIGTERM");
      } catch {
        // Already dead
      }

      removeCompassState();
      console.log(`[ok] Visualizer stopped (PID ${pid})`);
    });

  view
    .command("status")
    .description("Show visualizer status")
    .action(() => {
      const pid = readAlivePid();
      if (pid) {
        console.log(`[ok] Visualizer is running (PID ${pid})`);
        // Now that the port is recorded, status can answer the question people
        // actually run it to answer. Shares runningInstanceLines with the
        // already-running branch above so the two cannot drift: an instance
        // started before the port file existed still has no port to report, and
        // saying so beats printing nothing to someone who ran status *for* the
        // URL. Never guessed either way — a confidently wrong URL is #358.
        // `status` takes no -p, so the mismatch branch cannot fire here.
        for (const line of runningInstanceLines(readRunningPort(), 0, false)) {
          console.log(line);
        }
      } else {
        console.log("[--] Visualizer is not running.");
        console.log("  Run 'ix view' to start it.");
      }
    });
}