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
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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)) {