Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
// 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.");
}
});
}