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 { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
import { dirname, join } from "path";
import { ixHome } from "./ix-home.js";
import type { IxClient } from "../client/api.js";
import type { HealthResponse } from "../client/types.js";
/**
* Everything that reads or writes `~/.ix/.backend-version`.
*
* A leaf on purpose. `upgrade.ts` owns the update notice and imports
* `backend-status.ts`, so the stamp could not live in either without a cycle the
* moment `backend-status` needed to write it. Keeping it here lets the ONE
* function that fetches health also record what it read, which is what stops a
* future call site from silently forgetting to.
*/
/**
* The release the backend is believed to be running: `$IX_HOME/.backend-version`.
*
* A function, not a const, so the path follows IX_HOME as it is when the stamp
* is read or written rather than when this module was first imported -- see
* `ixHome()`.
*/
export function backendVersionFile(): string {
return join(ixHome(), ".backend-version");
}
/**
* The one definition of a valid version string, imported by upgrade.ts too.
*
* Copied rather than shared once already, and this exact pattern has shipped
* broken: written as a single `(?:[-+]...)?` group whose class omitted `+`, it
* rejected the valid tag `0.9.0-rc.1+abc1234` and `ix upgrade` exited 1 with
* "Could not reach GitHub" against a perfectly reachable GitHub. Two copies mean
* the next correction lands in one of them.
*/
export const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
/** Longer than any plausible tag; bounds a value the container controls. */
const MAX_VERSION_LENGTH = 64;
export function getTrackedVersion(versionFile: string): string {
try {
if (!existsSync(versionFile)) return "0.0.0";
return readFileSync(versionFile, "utf-8").trim() || "0.0.0";
} catch {
return "0.0.0";
}
}
/**
* Record a version stamp. Returns whether it was written.
*
* `mkdirSync` because IX_HOME may not exist yet. A falsy version is refused: not
* knowing which release we are on is not the same as being on none of them.
*
* NOT atomic, deliberately. `writeFileSync` opens with O_TRUNC, so a reader
* landing mid-write sees "" and is told a current backend is out of date — and
* this is now reachable from `ix status`/`ix map` while `checkForUpdate` reads
* the file on every command. Two things make that the better trade anyway:
* `recordBackendRelease` short-circuits when the stamp already agrees, so a
* write happens only when the backend's version actually CHANGES, not per
* command; and a temp-file-plus-rename replaces a file the caller may not have
* permission to write, since rename needs the directory rather than the file.
* That would silently change when the stamp-failure warning fires and would
* force the tests that pin it onto read-only directories, which Windows does not
* honour. Worth revisiting with an injection that works on both platforms.
*/
export function writeVersionStamp(
versionFile: string,
version: string | null | undefined,
): boolean {
if (!version) return false;
try {
mkdirSync(dirname(versionFile), { recursive: true });
writeFileSync(versionFile, version);
return true;
} catch {
return false;
}
}
/**
* Record what the backend says it is running.
*
* `.backend-version` was a record of what the CLI last INSTALLED, which is the
* same thing as what is RUNNING only while nothing else moves the image. Pull
* through docker compose and the file names an older release than the container,
* so the update notice fires on every command for ever. The container is the one
* thing that always knows, so it is asked rather than inferred.
*
* Three things bound a value the container controls, because this file decides
* whether the user is ever told about an upgrade again:
*
* - it is trimmed before matching. `getTrackedVersion` trims on the way out, and
* JavaScript's `$` does not match before a trailing newline, so without this a
* value from an --env-file or a ConfigMap silently fails the shape test and
* the whole feature no-ops with nothing to see.
* - it must be version-shaped and bounded in length. It is an env var an
* operator can set to anything.
* - it may NOT claim to be newer than the newest release we know of. Otherwise
* one container reporting `99.0.0` — a typo in a compose override, or a
* tampered image — permanently silences the notice AND makes `ix upgrade`
* report "already on the latest version" without ever pulling, so a security
* release can never reach that machine. When no release is known yet, only
* corrections that do not move the stamp forward are accepted, which still
* repairs a stamp stuck ahead and defers the rest until the cache exists.
*
* What the ceiling does NOT stop, stated plainly: a container that reports
* *exactly* the ceiling is accepted, and a compromised one has outbound network
* and can simply read the public release feed to learn that number rather than
* guess it. It then reaches the same silenced state by looking the answer up.
* This is a capability the feature introduces — before it, the stamp was
* written only by our own install/pull paths, so a container could not
* influence it at all. It is accepted deliberately: the alternative is to
* distrust the only component that actually knows what it is running, and the
* fail-safe direction (a container under-reporting, causing an unnecessary
* pull) is the one that stays open. `ix doctor`'s digest comparison remains the
* check that does not ask the container what it is.
*/
export function recordBackendRelease(
reported: string | null | undefined,
knownLatest: string | null | undefined,
isNewer: (a: string, b: string) => boolean,
): boolean {
const value = typeof reported === "string" ? reported.trim() : "";
if (!value || value.length > MAX_VERSION_LENGTH || !VERSION_RE.test(value)) return false;
const tracked = getTrackedVersion(backendVersionFile());
if (value === tracked) return false; // already agrees; do not touch the file
const ceiling =
typeof knownLatest === "string" && VERSION_RE.test(knownLatest.trim())
? knownLatest.trim()
: null;
// No published release can be older than what a container legitimately runs.
if (ceiling ? isNewer(value, ceiling) : isNewer(value, tracked)) return false;
return writeVersionStamp(backendVersionFile(), value);
}
/**
* True when this endpoint is the local backend the update notice is about.
*
* The stamp is global (`~/.ix/.backend-version`) but the endpoint is per
* invocation, so `IX_ENDPOINT=http://staging:8090 ix status` would otherwise
* record a different deployment's release into the file that governs the LOCAL
* docker image notice — a newer remote silencing a genuinely stale local
* backend, or an older one nagging about a current one.
*/
export function isLocalEndpoint(endpoint: string): boolean {
try {
// A trailing dot is the fully-qualified form and resolvers accept it.
const host = new URL(endpoint).hostname.toLowerCase().replace(/\.$/, "");
return (
host === "localhost" ||
/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host) || // 127.0.0.0/8, as an ADDRESS
// ...not a prefix: `127.0.0.1.evil.com` is a remote name that starts "127."
host === "0.0.0.0" || // what client/api.ts and errors.ts already accept
host === "[::1]" // new URL() always brackets IPv6, so bare "::1" is unreachable
);
} catch {
return false;
}
}
/**
* Fetch `/v1/health` AND record the release it reports.
*
* The single place either happens. Every command that READS a health body goes
* through here, so "a new call site forgot to record" is not a mistake that can
* be made — which is worth more than the grep-based drift guard it replaces.
*
* Precisely: reads of the body. docker.ts and upgrade.ts also hit /v1/health via
* `curl -sf` with stdio ignored, purely as a readiness poll; they discard the
* response, so there is nothing there to record.
*/
export async function fetchBackendHealth(
client: IxClient,
knownLatest: string | null | undefined,
isNewer: (a: string, b: string) => boolean,
/** Bounds a probe that must answer in seconds; the client's default otherwise. */
timeoutMs?: number,
): Promise<HealthResponse> {
const health = await client.health(timeoutMs);
// From the client the request actually went to. Taking it as a second
// argument reintroduced exactly the "a call site can get it wrong" mistake
// this module exists to make impossible.
// `health?.` because a 200 whose body is literally `null` parses to null.
// The contract of this function is "return whatever the backend sent"; adding
// a throw of its own would be this bookkeeping changing the outcome of a
// request that succeeded. Nothing more is claimed: status.ts dereferences
// health.status unguarded moments later, so on a null body it fails either
// way — the `?.` keeps the failure the caller's, not ours.
if (isLocalEndpoint(client.endpoint)) {
recordBackendRelease(health?.release_version, knownLatest, isNewer);
}
return health;
}