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
fix(view): stop serving a cached Compass over a new install (#460)
KageBinary3eb3fe8f1416
diff --git a/ix-cli/src/cli/__tests__/view-running-port.test.ts b/ix-cli/src/cli/__tests__/view-running-port.test.tsindex e937cabe..78e35b66 100644--- a/ix-cli/src/cli/__tests__/view-running-port.test.ts+++ b/ix-cli/src/cli/__tests__/view-running-port.test.ts@@ -267,15 +267,18 @@ describe("view running port state", () => {describe("runningInstanceLines", () => {it("never builds a URL from the requested port", async () => {const { runningInstanceLines } = await import("../commands/view.js");- const lines = runningInstanceLines(19123, 19124, true);+ // The token is supplied so the assertion stays exact; it is the cache bust+ // that makes an already-running visualizer reachable after `ix upgrade`+ // replaced the dist underneath it.+ const lines = runningInstanceLines(19123, 19124, true, "tok");- expect(lines[0]).toBe(" http://localhost:19123");+ expect(lines[0]).toBe(" http://localhost:19123/?ix=tok");expect(lines.some(l => l.includes("http://localhost:19124"))).toBe(false);});it("does not warn when the running port is the one that was asked for", async () => {const { runningInstanceLines } = await import("../commands/view.js");- expect(runningInstanceLines(8080, 8080, true)).toEqual([" http://localhost:8080"]);+ expect(runningInstanceLines(8080, 8080, true, "tok")).toEqual([" http://localhost:8080/?ix=tok"]);});it("admits it does not know rather than guessing", async () => {diff --git a/ix-cli/src/cli/__tests__/view-server.test.ts b/ix-cli/src/cli/__tests__/view-server.test.tsindex 37f4c349..86e5a03e 100644--- a/ix-cli/src/cli/__tests__/view-server.test.ts+++ b/ix-cli/src/cli/__tests__/view-server.test.ts@@ -1,11 +1,12 @@import { afterAll, beforeAll, describe, expect, it } from "vitest";import { spawn, type ChildProcess } from "node:child_process";-import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";+import { mkdirSync, mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";import { createServer } from "node:net";+import { Script } from "node:vm";import * as http from "node:http";-import { serverRuntimeArgs, serverScript } from "../commands/view.js";+import { browserUrl, runningInstanceLines, serverRuntimeArgs, serverScript } from "../commands/view.js";interface StartServerOptions {workspaceId?: string;@@ -370,4 +371,173 @@ describe("view server (/__ix/remap)", () => {await new Promise<void>((resolve) => hung.close(() => resolve()));}}, 20000);++ // ── Cache headers ────────────────────────────────────────────────────────+ //+ // Reported as "it reads the new release but looks the same": rc.10 installed,+ // /.version showed the new stamp, and the screen showed the previous build.+ // The server sent no cache headers at all — which is not "do not cache". With+ // no Cache-Control, no ETag and no Last-Modified the browser picks its own+ // freshness heuristic, and `ix view` reuses 127.0.0.1 on the same port across+ // upgrades, so the entry point it cached before the upgrade is still a hit+ // after it. The old index.html then names the old hashed bundles and the+ // whole previous Compass runs, while /.version is fetched separately and+ // reports the new build.++ it("never lets the entry point be served from cache", async () => {+ await startServer({ STUB_EXIT: "0" });+ const res = await fetch(`http://127.0.0.1:${port}/`);+ expect(res.status).toBe(200);+ expect(res.headers.get("cache-control")).toBe("no-store");+ }, 20000);++ it("never lets the build stamp be served from cache", async () => {+ // The stamp is what a bug report quotes. A stale one is worse than none:+ // it makes the wrong build look like the right one.+ writeFileSync(join(distDir, ".version"), "0.10.0-rc.10+release.6bce261\n");+ await startServer({ STUB_EXIT: "0" });+ const res = await fetch(`http://127.0.0.1:${port}/.version`);+ expect(res.status).toBe(200);+ expect(await res.text()).toContain("0.10.0-rc.10");+ expect(res.headers.get("cache-control")).toBe("no-store");+ }, 20000);++ it("keeps fingerprinted assets cacheable", async () => {+ // The point is not to disable caching — everything under assets/ is named+ // by its own content, so it is safe to keep and expensive to refetch.+ mkdirSync(join(distDir, "assets"), { recursive: true });+ writeFileSync(join(distDir, "assets", "index-BbVrNAev.js"), "export const x = 1;\n");+ await startServer({ STUB_EXIT: "0" });+ const res = await fetch(`http://127.0.0.1:${port}/assets/index-BbVrNAev.js`);+ expect(res.status).toBe(200);+ expect(res.headers.get("cache-control")).toBe("public, max-age=31536000, immutable");+ }, 20000);++ it("does not let a missing asset poison the cache with the SPA fallback", async () => {+ // A stale index.html asks for a bundle that no longer exists. The fallback+ // answers with index.html, and caching *that* under the asset's URL is how+ // one bad load becomes permanent.+ await startServer({ STUB_EXIT: "0" });+ const res = await fetch(`http://127.0.0.1:${port}/assets/index-GONE.js`);+ expect(res.headers.get("cache-control")).toBe("no-store");+ }, 20000);++ it("only marks a file immutable when its name carries a content hash", async () => {+ // Being under assets/ is not the claim that makes a year-long pin safe --+ // a name that changes with the bytes is, and Compass is built in another+ // repo, so nothing here can verify what it puts in that directory. One+ // stable name pinned for a year against a fixed origin has no revalidation+ // path and no recovery short of clearing site data.+ mkdirSync(join(distDir, "assets"), { recursive: true });+ writeFileSync(join(distDir, "assets", "logo.svg"), "<svg/>");+ writeFileSync(join(distDir, "assets", "vendor-2f9ab31c.css"), "body{}");+ await startServer({ STUB_EXIT: "0" });++ const unhashed = await fetch(`http://127.0.0.1:${port}/assets/logo.svg`);+ expect(unhashed.status).toBe(200);+ expect(unhashed.headers.get("cache-control")).toBe("no-store");++ const hashed = await fetch(`http://127.0.0.1:${port}/assets/vendor-2f9ab31c.css`);+ expect(hashed.status).toBe(200);+ expect(hashed.headers.get("cache-control")).toBe("public, max-age=31536000, immutable");+ }, 20000);++ it("refuses to read outside the dist directory", async () => {+ // url.parse leaves dot-dot segments intact and path.join resolves straight+ // out of the tree. A browser normalises the path before sending, so the+ // reader here is another local process -- which still gets a file read as+ // whoever ran the CLI. --path-as-is is how curl reproduces it; fetch()+ // normalises, so the request is built by hand.+ await startServer({ STUB_EXIT: "0" });+ const outside = join(distDir, "..", "outside-secret.txt");+ writeFileSync(outside, "top secret");+ try {+ const status = await new Promise<{ code: number; body: string }>((resolve, reject) => {+ const req = http.request(+ { host: "127.0.0.1", port, path: "/../outside-secret.txt", method: "GET" },+ (res) => {+ let body = "";+ res.on("data", (c) => (body += c));+ res.on("end", () => resolve({ code: res.statusCode ?? 0, body }));+ },+ );+ req.on("error", reject);+ req.end();+ });+ expect(status.body).not.toContain("top secret");+ expect(status.code).toBe(404);+ } finally {+ rmSync(outside, { force: true });+ }+ }, 20000);++ it("does not let an extensionless /assets/ miss poison the cache", async () => {+ // The case above has an extension, so it takes the readFile-error branch+ // and its hardcoded no-store — it never reaches the asset/entry decision at+ // all. Without an extension the *earlier* SPA rewrite fires instead:+ // filePath becomes index.html and readFile succeeds, so the response body+ // is the entry point while the URL still says /assets/. Choosing the policy+ // from the URL stamps that body `immutable` for a year, which is this bug+ // made permanent. Choosing it from the resolved file does not.+ await startServer({ STUB_EXIT: "0" });+ const res = await fetch(`http://127.0.0.1:${port}/assets/index-GONE`);+ expect(res.status).toBe(200);+ // Proof the body really is the entry point, not a 404 that happens to+ // carry the right header.+ expect(await res.text()).toContain("fake compass");+ expect(res.headers.get("cache-control")).toBe("no-store");+ }, 20000);++});++// ── Entry-point cache busting ────────────────────────────────────────────────+//+// `no-store` fixes the *next* upgrade. It cannot fix the one the reporter just+// ran: their browser cached `/` before it, so it never issues the request that+// would carry the new header. A different query string is a different cache+// key, which is the only thing that reaches an entry the browser is not asking+// about.+describe("view URLs", () => {+ it("busts the cache key on every URL the CLI names", () => {+ expect(browserUrl("http://localhost:4173", "abc123")).toBe(+ "http://localhost:4173/?ix=abc123",+ );+ // The already-running branch is the reporter's path: `ix upgrade` replaces+ // the dist in place and leaves the server up, so the next `ix view` prints+ // a URL and opens nothing. A bust on the opened tab alone would miss it.+ expect(runningInstanceLines(8080, 8080, false, "abc123")).toEqual([+ " http://localhost:8080/?ix=abc123",+ ]);+ // …and the port-mismatch advice still comes with it.+ expect(runningInstanceLines(19123, 19124, true, "abc123")[0]).toBe(+ " http://localhost:19123/?ix=abc123",+ );+ });++ it("uses a fresh key per invocation rather than 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.+ // A stamp would have to be read from the dist — which a dev build does not+ // have, exactly where an iterating developer needs this most.+ expect(browserUrl("http://localhost:4173")).toMatch(/^http:\/\/localhost:4173\/\?ix=[a-z0-9]+$/);+ expect(browserUrl("http://localhost:4173")).toBe(browserUrl("http://localhost:4173"));+ });+});++// The server script is emitted from a template literal, so a stray backtick+// anywhere in it — including inside a comment — ends the literal, and a+// backslash escape is eaten before it reaches the generated file. Both have+// happened; the second took the server down, and a backtick in a comment+// warning about backticks is what broke this block most recently. Compiling+// the emitted source is the check that would have caught every one of them.+describe("generated server script", () => {+ it("is syntactically valid JavaScript", () => {+ expect(() => new Script(serverScript())).not.toThrow();+ });++ it("carries no backtick or backslash into the emitted file", () => {+ const script = serverScript();+ expect(script).not.toContain("`");+ expect(script).not.toContain("\\");+ });});diff --git a/ix-cli/src/cli/commands/view.ts b/ix-cli/src/cli/commands/view.tsindex 2788bb9c..36f9e407 100644--- a/ix-cli/src/cli/commands/view.ts+++ b/ix-cli/src/cli/commands/view.ts@@ -126,11 +126,18 @@ function readRunningPort(): number | null {** 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 [@@ -139,7 +146,7 @@ export function runningInstanceLines(];}- const lines = [` http://localhost:${runningPort}`];+ 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.`);@@ -311,6 +318,50 @@ const MIME = {".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";+const server = http.createServer((req, res) => {const parsed = url.parse(req.url);const pathname = parsed.pathname || "/";@@ -449,8 +500,22 @@ const server = http.createServer((req, res) => {return;}- // Serve static files- let filePath = path.join(DIST, pathname === "/" ? "index.html" : pathname);+ // 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.htmlif (!fs.existsSync(filePath) && !path.extname(filePath)) {@@ -466,14 +531,20 @@ const server = http.createServer((req, res) => {res.end("Not found");return;}- res.writeHead(200, { "Content-Type": "text/html" });+ 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 });+ res.writeHead(200, {+ "Content-Type": mime,+ "Cache-Control": cacheControl(filePath),+ });res.end(data);});});@@ -484,6 +555,43 @@ server.listen(PORT, "127.0.0.1", () => {`;}+/**+ * 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}`;+}+function openBrowser(url: string): void {try {const plat = platform();@@ -647,7 +755,11 @@ export function registerViewCommand(program: Command): void {writeFileSync(SCOPE_FILE, scopeKey);writeFileSync(PORT_FILE, String(port));- const url = `http://localhost:${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