Skip to content

armgit / Ix

Public Imported from GitHub
0

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

feat(doctor,upgrade): verify running backend image + prompt re-map on update (#275)

Joseph Mikhaile807c556b1c3
diff --git a/ix-cli/src/cli/__tests__/backend-status.test.ts b/ix-cli/src/cli/__tests__/backend-status.test.ts
new file mode 100644
index 00000000..cdfa4a26
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/backend-status.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+import {
+ CLIENT_EXPECTED_SCHEMA_VERSION,
+ checkBackendSchema,
+ isNonStandardBackend,
+ type BackendContainer,
+} from "../backend-status.js";
+import type { IxClient } from "../../client/api.js";
+
+function fakeClient(health: () => Promise<any>): IxClient {
+ return { health } as unknown as IxClient;
+}
+
+function container(overrides: Partial<BackendContainer>): BackendContainer {
+ return {
+ containerId: "abc123",
+ imageRef: "ghcr.io/ix-infrastructure/ix-memory-layer:latest",
+ imageId: "sha256:deadbeef",
+ repoDigests: [],
+ composeProject: "ix",
+ composeConfigFiles: null,
+ ...overrides,
+ };
+}
+
+describe("checkBackendSchema", () => {
+ it("matches when the backend reports the expected version", async () => {
+ const s = await checkBackendSchema(fakeClient(async () => ({ status: "ok", schema_version: CLIENT_EXPECTED_SCHEMA_VERSION })));
+ expect(s).toEqual({ reachable: true, serverVersion: CLIENT_EXPECTED_SCHEMA_VERSION, expected: CLIENT_EXPECTED_SCHEMA_VERSION, matches: true });
+ });
+
+ it("flags a mismatch when the persisted graph predates the engine", async () => {
+ const s = await checkBackendSchema(fakeClient(async () => ({ status: "ok", schema_version: CLIENT_EXPECTED_SCHEMA_VERSION - 1 })));
+ expect(s.matches).toBe(false);
+ expect(s.serverVersion).toBe(CLIENT_EXPECTED_SCHEMA_VERSION - 1);
+ });
+
+ it("does not flag when the backend reports no schema version (can't prove stale)", async () => {
+ const s = await checkBackendSchema(fakeClient(async () => ({ status: "ok" })));
+ expect(s.matches).toBe(true);
+ expect(s.serverVersion).toBeNull();
+ });
+
+ it("reports unreachable (and does not flag) when health throws", async () => {
+ const s = await checkBackendSchema(fakeClient(async () => { throw new Error("ECONNREFUSED"); }));
+ expect(s).toEqual({ reachable: false, serverVersion: null, expected: CLIENT_EXPECTED_SCHEMA_VERSION, matches: true });
+ });
+});
+
+describe("isNonStandardBackend", () => {
+ const standard = join(homedir(), ".ix", "backend", "docker-compose.yml");
+
+ it("treats a compose project under ~/.ix/backend as standard", () => {
+ expect(isNonStandardBackend(container({ composeConfigFiles: standard }))).toBe(false);
+ });
+
+ it("flags a compose project outside ~/.ix/backend", () => {
+ expect(isNonStandardBackend(container({ composeConfigFiles: "/work/ix-memory-layer/docker-compose.yml" }))).toBe(true);
+ });
+
+ it("does not flag when no compose config files are known", () => {
+ expect(isNonStandardBackend(container({ composeConfigFiles: null }))).toBe(false);
+ });
+});
diff --git a/ix-cli/src/cli/backend-status.ts b/ix-cli/src/cli/backend-status.ts
new file mode 100644
index 00000000..6b377cb5
--- /dev/null
+++ b/ix-cli/src/cli/backend-status.ts
@@ -0,0 +1,152 @@
+// Backend freshness helpers (Ix#270, Ix#271).
+//
+// Two distinct staleness problems can make a healthy-looking backend serve
+// wrong/empty results:
+// 1. The running CONTAINER is not the released image (a local dev build, or an
+// older digest), yet `ix upgrade` thinks it is current because it trusts the
+// ~/.ix/.backend-version stamp instead of the running image (Ix#270).
+// 2. The persisted GRAPH predates the running engine's on-disk format, so
+// scoped reads silently return empty until the user re-maps (Ix#271).
+//
+// This module inspects the actual running container and compares the backend's
+// reported schema_version against what this CLI expects, so `ix doctor` and
+// `ix upgrade` can surface both instead of looking mysteriously broken.
+
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { IxClient } from "../client/api.js";
+
+export const BACKEND_IMAGE = "ghcr.io/ix-infrastructure/ix-memory-layer";
+const BACKEND_PORT = "8090";
+const IX_HOME = process.env.IX_HOME || join(homedir(), ".ix");
+const STANDARD_BACKEND_DIR = join(IX_HOME, "backend");
+
+// On-disk graph format this CLI expects. MUST stay in sync with the backend's
+// reported schema_version; a mismatch forces a full re-ingest (see ingest.ts,
+// which imports this constant). Bump when the node-identity/format changes.
+export const CLIENT_EXPECTED_SCHEMA_VERSION = 3;
+
+function docker(args: string[], timeout = 10000): string | null {
+ try {
+ return execFileSync("docker", args, { encoding: "utf-8", timeout }).trim();
+ } catch {
+ return null;
+ }
+}
+
+export function dockerAvailable(): boolean {
+ return docker(["info"]) !== null;
+}
+
+export interface BackendContainer {
+ containerId: string;
+ /** Image reference the container was created from (e.g. ghcr.io/...:latest). */
+ imageRef: string;
+ /** Resolved image content id (sha256:...) the container is actually running. */
+ imageId: string;
+ /** Registry digests of that image; empty for a never-pushed local build. */
+ repoDigests: string[];
+ composeProject: string | null;
+ composeConfigFiles: string | null;
+}
+
+/** Inspect the container currently publishing the backend port, if any. */
+export function inspectBackendContainer(): BackendContainer | null {
+ const ids = docker(["ps", "--filter", `publish=${BACKEND_PORT}`, "--format", "{{.ID}}"]);
+ if (!ids) return null;
+ const containerId = ids.split("\n")[0]?.trim();
+ if (!containerId) return null;
+
+ // A unique separator keeps Go-template parsing robust against odd image refs.
+ const SEP = "|::|";
+ const fmt =
+ `{{.Image}}${SEP}{{.Config.Image}}` +
+ `${SEP}{{index .Config.Labels "com.docker.compose.project"}}` +
+ `${SEP}{{index .Config.Labels "com.docker.compose.project.config_files"}}`;
+ const inspected = docker(["inspect", containerId, "--format", fmt]);
+ if (!inspected) return null;
+ const [imageId = "", imageRef = "", project = "", configFiles = ""] = inspected.split(SEP);
+
+ let repoDigests: string[] = [];
+ const digestsJson = docker(["image", "inspect", imageId || imageRef, "--format", "{{json .RepoDigests}}"]);
+ if (digestsJson) {
+ try {
+ const parsed = JSON.parse(digestsJson);
+ if (Array.isArray(parsed)) repoDigests = parsed;
+ } catch {
+ /* leave empty */
+ }
+ }
+
+ return {
+ containerId,
+ imageRef,
+ imageId,
+ repoDigests,
+ composeProject: project || null,
+ composeConfigFiles: configFiles || null,
+ };
+}
+
+export type BackendImageStatus =
+ | { kind: "ok"; container: BackendContainer }
+ | { kind: "local-build"; container: BackendContainer }
+ | { kind: "digest-mismatch"; container: BackendContainer; latestImageId: string }
+ | { kind: "latest-not-pulled"; container: BackendContainer }
+ | { kind: "not-running" }
+ | { kind: "docker-unavailable" };
+
+/**
+ * Compare the running backend container against the locally-pulled released
+ * `:latest` image. Conclusions only when we can prove a mismatch; an
+ * inconclusive state (latest not pulled, docker down) never reports a problem.
+ */
+export function checkBackendImage(): BackendImageStatus {
+ if (!dockerAvailable()) return { kind: "docker-unavailable" };
+ const container = inspectBackendContainer();
+ if (!container) return { kind: "not-running" };
+
+ const latestImageId = docker(["image", "inspect", `${BACKEND_IMAGE}:latest`, "--format", "{{.Id}}"]);
+ if (!latestImageId) return { kind: "latest-not-pulled", container };
+
+ if (container.imageId === latestImageId) return { kind: "ok", container };
+
+ // Different from the released image. A container with no registry digests (or
+ // one not built from the released repo) is a local build; otherwise it is an
+ // older/divergent pulled digest.
+ const isReleasedRepo = container.repoDigests.some((d) => d.startsWith(BACKEND_IMAGE + "@"));
+ if (container.repoDigests.length === 0 || !isReleasedRepo) {
+ return { kind: "local-build", container };
+ }
+ return { kind: "digest-mismatch", container, latestImageId };
+}
+
+/** True when the running backend uses a compose project outside ~/.ix/backend. */
+export function isNonStandardBackend(container: BackendContainer): boolean {
+ const cfg = container.composeConfigFiles;
+ if (!cfg) return false;
+ return !cfg.split(",").some((p) => p.trim().startsWith(STANDARD_BACKEND_DIR));
+}
+
+export interface BackendSchemaStatus {
+ reachable: boolean;
+ serverVersion: number | null;
+ expected: number;
+ matches: boolean;
+}
+
+/** Read the backend's reported schema_version and compare to what we expect. */
+export async function checkBackendSchema(client: IxClient): Promise<BackendSchemaStatus> {
+ const expected = CLIENT_EXPECTED_SCHEMA_VERSION;
+ try {
+ const health = await client.health();
+ const serverVersion = typeof health.schema_version === "number" ? health.schema_version : null;
+ // No reported version (older backend) is treated as a match: we can't prove
+ // staleness, and the ingest path already forces a re-ingest when it can.
+ const matches = serverVersion === null || serverVersion === expected;
+ return { reachable: true, serverVersion, expected, matches };
+ } catch {
+ return { reachable: false, serverVersion: null, expected, matches: true };
+ }
+}
diff --git a/ix-cli/src/cli/commands/doctor.ts b/ix-cli/src/cli/commands/doctor.ts
index 2932a1d5..2ab89c55 100644
--- a/ix-cli/src/cli/commands/doctor.ts
+++ b/ix-cli/src/cli/commands/doctor.ts
@@ -3,10 +3,24 @@ import chalk from "chalk";
import { renderSection, renderSuccess, renderError } from "../ui.js";
import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
+import {
+ BACKEND_IMAGE,
+ checkBackendImage,
+ checkBackendSchema,
+ isNonStandardBackend,
+} from "../backend-status.js";
+
+interface CheckResult {
+ ok: boolean;
+ detail: string;
+ // A warning is surfaced (yellow) but does not fail the overall run — e.g. an
+ // intentional local dev backend, or an inconclusive image comparison.
+ warn?: boolean;
+}
interface Check {
name: string;
- run: () => Promise<{ ok: boolean; detail: string }>;
+ run: () => Promise<CheckResult>;
}
export function registerDoctorCommand(program: Command): void {
@@ -66,34 +80,88 @@ export function registerDoctorCommand(program: Command): void {
}
},
},
+ {
+ // Ix#270: trust the running container, not the version stamp.
+ name: "Backend is the released image",
+ run: async () => {
+ const status = checkBackendImage();
+ switch (status.kind) {
+ case "ok": {
+ if (isNonStandardBackend(status.container)) {
+ return {
+ ok: false, warn: true,
+ detail: `released image, but via a non-standard compose project (${status.container.composeProject ?? "unknown"})`,
+ };
+ }
+ return { ok: true, detail: "running the released image" };
+ }
+ case "local-build":
+ return {
+ ok: false, warn: true,
+ detail: `running a local build (${status.container.imageRef}), not the released image — ` +
+ `'ix docker stop && ix docker start' pulls ${BACKEND_IMAGE}:latest`,
+ };
+ case "digest-mismatch":
+ return {
+ ok: false, warn: true,
+ detail: "running an older image digest than :latest — " +
+ "'ix docker stop && ix docker start' pulls the released image",
+ };
+ case "latest-not-pulled":
+ return { ok: true, warn: true, detail: `can't verify — ${BACKEND_IMAGE}:latest not pulled locally` };
+ case "not-running":
+ return { ok: true, detail: "no backend container on :8090 (skipped)" };
+ case "docker-unavailable":
+ return { ok: true, detail: "docker unavailable (skipped)" };
+ }
+ },
+ },
+ {
+ // Ix#271: a graph written by an older engine fails scoped reads silently.
+ name: "Graph schema matches engine",
+ run: async () => {
+ const s = await checkBackendSchema(client);
+ if (!s.reachable) return { ok: true, detail: "backend unreachable (skipped)" };
+ if (s.serverVersion === null) return { ok: true, detail: "backend does not report a schema version" };
+ if (s.matches) return { ok: true, detail: `schema v${s.serverVersion}` };
+ return {
+ ok: false, warn: true,
+ detail: `graph schema v${s.serverVersion}, this CLI expects v${s.expected} — ` +
+ "re-map to rebuild the graph: 'ix map .'",
+ };
+ },
+ },
];
- const results: Array<{ name: string; ok: boolean; detail: string }> = [];
+ const results: Array<{ name: string } & CheckResult> = [];
for (const check of checks) {
const result = await check.run();
results.push({ name: check.name, ...result });
}
+ const hasFailure = results.some((r) => !r.ok && !r.warn);
+ const hasWarning = results.some((r) => r.warn);
+
if (opts.format === "json") {
- const allOk = results.every((r) => r.ok);
- console.log(JSON.stringify({ healthy: allOk, checks: results }, null, 2));
+ console.log(JSON.stringify({ healthy: !hasFailure, hasWarnings: hasWarning, checks: results }, null, 2));
return;
}
renderSection("Ix Doctor");
console.log();
for (const r of results) {
- const icon = r.ok ? chalk.green("✓") : chalk.red("✗");
+ const icon = r.ok ? chalk.green("✓") : r.warn ? chalk.yellow("!") : chalk.red("✗");
const detail = chalk.dim(` — ${r.detail}`);
console.log(` ${icon} ${r.name}${detail}`);
}
- const allOk = results.every((r) => r.ok);
console.log();
- if (allOk) {
- renderSuccess("All checks passed.");
- } else {
+ if (hasFailure) {
renderError("Some checks failed. Run with --format json for details.");
+ } else if (hasWarning) {
+ renderSuccess("All checks passed (with warnings).");
+ } else {
+ renderSuccess("All checks passed.");
}
console.log();
});
diff --git a/ix-cli/src/cli/commands/ingest.ts b/ix-cli/src/cli/commands/ingest.ts
index c6c2916e..c8007ae6 100644
--- a/ix-cli/src/cli/commands/ingest.ts
+++ b/ix-cli/src/cli/commands/ingest.ts
@@ -16,6 +16,7 @@ import { parseGitHubRepo, fetchGitHubData } from '../github/fetch.js';
import { loadIngestionModules } from './ingestion-loader.js';
import { ensureWorkspaceIdState } from '../bootstrap.js';
import { detectSystem, repoWorkspaceIdFor, lookupPackage, readPackageNames, readPackageDeps } from '../system.js';
+import { CLIENT_EXPECTED_SCHEMA_VERSION } from '../backend-status.js';
import {
deterministicId,
transformIssue,
@@ -580,7 +581,7 @@ export async function ingestFiles(
// Schema-version check forces a clean re-ingest when the backend's graph
// format has changed in a way that invalidates existing node IDs (e.g. the
// absolute→relative source_uri migration, or folding workspace_id into ids).
- const CLIENT_EXPECTED_SCHEMA_VERSION = 3;
+ // CLIENT_EXPECTED_SCHEMA_VERSION is shared with doctor/upgrade (backend-status).
try {
const health = await client.health();
const serverVersion = (health as any)?.schema_version;
diff --git a/ix-cli/src/cli/commands/upgrade.ts b/ix-cli/src/cli/commands/upgrade.ts
index b6b8af68..6c546f3a 100644
--- a/ix-cli/src/cli/commands/upgrade.ts
+++ b/ix-cli/src/cli/commands/upgrade.ts
@@ -5,6 +5,7 @@ import { dirname, join } from "path";
import { fileURLToPath } from "url";
import { homedir, tmpdir } from "os";
import chalk from "chalk";
+import { BACKEND_IMAGE, checkBackendImage, isNonStandardBackend } from "../backend-status.js";
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
@@ -265,6 +266,7 @@ export function registerUpgradeCommand(program: Command): void {
// ── Backend (memory-layer) upgrade ───────────────────────────────
const backendCurrent = getTrackedVersion(BACKEND_VERSION_FILE);
+ let backendImageChanged = false;
if (backendLatest && isNewer(backendLatest, backendCurrent)) {
console.log(
`Backend update available: ${backendCurrent === "0.0.0" ? "none" : backendCurrent} → ${chalk.green(backendLatest)}`
@@ -280,6 +282,7 @@ export function registerUpgradeCommand(program: Command): void {
);
mkdirSync(IX_HOME, { recursive: true });
writeFileSync(BACKEND_VERSION_FILE, backendLatest);
+ backendImageChanged = true;
console.log(`[ok] Backend image updated to ${backendLatest}`);
} catch {
console.error("[!!] Could not pull latest backend image. Run: ix docker restart");
@@ -311,6 +314,41 @@ export function registerUpgradeCommand(program: Command): void {
console.log("[--] Could not check backend version");
}
+ // ── Backend running-image verification (Ix#270) ──────────────────
+ // The version stamp above only reflects what was last pulled, not what is
+ // actually running. Inspect the live container so a stale local/dev image
+ // is surfaced even when the stamp reads current.
+ if (!opts.check) {
+ const imageStatus = checkBackendImage();
+ if (imageStatus.kind === "local-build") {
+ console.log(
+ chalk.yellow(
+ `[!!] Backend container is a local build (${imageStatus.container.imageRef}), not the released image.`
+ )
+ );
+ console.log(chalk.dim(" Run: ix docker stop && ix docker start (pulls " + BACKEND_IMAGE + ":latest)"));
+ } else if (imageStatus.kind === "digest-mismatch") {
+ console.log(chalk.yellow("[!!] Backend container is running an older image digest than :latest."));
+ console.log(chalk.dim(" Run: ix docker stop && ix docker start (pulls the released image)"));
+ } else if (imageStatus.kind === "ok" && isNonStandardBackend(imageStatus.container)) {
+ console.log(
+ chalk.yellow(
+ `[!!] Backend is served by a non-standard compose project (${imageStatus.container.composeProject ?? "unknown"}), not ~/.ix/backend.`
+ )
+ );
+ }
+ }
+
+ // ── Re-map prompt after a backend update (Ix#271) ────────────────
+ // A graph written by the previous engine may lack fields the new read
+ // paths filter on (workspace_id/system_id), so scoped reads return empty
+ // until the user re-maps. Nudge them once, right after the image changes.
+ if (backendImageChanged) {
+ console.log("");
+ console.log(chalk.yellow(" Backend engine updated. Re-map your repositories so the graph matches:"));
+ console.log(chalk.dim(" ix map ."));
+ }
+
// ── Compass upgrade ──────────────────────────────────────────────
const compassCurrent = getTrackedVersion(COMPASS_VERSION_FILE);
if (compassLatest && isNewer(compassLatest, compassCurrent)) {