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
v0.6.0: install fixes, client-agnostic backend, view port option (#193)
Riley Thompson6ab8141d2df9
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 46b17e03..3ae728be 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -89,8 +89,8 @@ jobs:run: |STAGING="ix-${{ steps.version.outputs.version }}-linux-amd64"mkdir -p "$STAGING/cli" "$STAGING/core-ingestion" "$STAGING/compass"- cp -r ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"- cp -r core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"+ cp -rL ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"+ cp -rL core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"[ -d system-compass/dist ] && cp -r system-compass/dist/* "$STAGING/compass/" || truecat > "$STAGING/ix" <<'WRAPPER'#!/bin/sh@@ -105,8 +105,8 @@ jobs:run: |STAGING="ix-${{ steps.version.outputs.version }}-linux-arm64"mkdir -p "$STAGING/cli" "$STAGING/core-ingestion" "$STAGING/compass"- cp -r ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"- cp -r core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"+ cp -rL ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"+ cp -rL core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"[ -d system-compass/dist ] && cp -r system-compass/dist/* "$STAGING/compass/" || truecat > "$STAGING/ix" <<'WRAPPER'#!/bin/sh@@ -121,8 +121,8 @@ jobs:run: |STAGING="ix-${{ steps.version.outputs.version }}-darwin-amd64"mkdir -p "$STAGING/cli" "$STAGING/core-ingestion" "$STAGING/compass"- cp -r ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"- cp -r core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"+ cp -rL ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"+ cp -rL core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"[ -d system-compass/dist ] && cp -r system-compass/dist/* "$STAGING/compass/" || truecat > "$STAGING/ix" <<'WRAPPER'#!/bin/sh@@ -137,8 +137,8 @@ jobs:run: |STAGING="ix-${{ steps.version.outputs.version }}-darwin-arm64"mkdir -p "$STAGING/cli" "$STAGING/core-ingestion" "$STAGING/compass"- cp -r ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"- cp -r core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"+ cp -rL ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"+ cp -rL core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"[ -d system-compass/dist ] && cp -r system-compass/dist/* "$STAGING/compass/" || truecat > "$STAGING/ix" <<'WRAPPER'#!/bin/sh@@ -153,8 +153,8 @@ jobs:run: |STAGING="ix-${{ steps.version.outputs.version }}-windows-amd64"mkdir -p "$STAGING/cli" "$STAGING/core-ingestion" "$STAGING/compass"- cp -r ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"- cp -r core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"+ cp -rL ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"+ cp -rL core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"[ -d system-compass/dist ] && cp -r system-compass/dist/* "$STAGING/compass/" || truecat > "$STAGING/ix.cmd" <<'WRAPPER'@echo offdiff --git a/README.md b/README.mdindex 9e726140..045e65a5 100644--- a/README.md+++ b/README.md@@ -105,6 +105,7 @@ gemini extensions install https://github.com/ix-infrastructure/ix-gemini-plugin## Requirements- macOS, Linux, or Windows+- Node.js 20 or newer- Git installed- Docker (for full functionality)diff --git a/core-ingestion/src/types.ts b/core-ingestion/src/types.tsindex 01bacd7b..d5182d44 100644--- a/core-ingestion/src/types.ts+++ b/core-ingestion/src/types.ts@@ -1,8 +1,14 @@export interface PatchSource {+ // uri is the provenance source URI. In the client-agnostic backend design it+ // is a workspace-relative path (POSIX separators), not an absolute host path.uri: string;sourceHash?: string;extractor: string;sourceType: string;+ // workspaceId uniquely identifies the workspace whose files produced this+ // patch. Derived client-side (SHA-256 of workspace root abs path). Backend+ // stores it as an opaque attribute.+ workspaceId?: string;}export interface PatchOp {diff --git a/docker-compose.standalone.yml b/docker-compose.standalone.ymlindex a6734a18..04cb048d 100644--- a/docker-compose.standalone.yml+++ b/docker-compose.standalone.yml@@ -30,11 +30,6 @@ services:- backendports:- "127.0.0.1:8090:8090"- volumes:- - type: bind- source: ${IX_HOST_MOUNT_ROOT:-$HOME}- target: ${IX_CONTAINER_MOUNT_ROOT:-$HOME}- read_only: trueenvironment:ARANGO_HOST: arangodbARANGO_PORT: "8529"diff --git a/ix-cli/package.json b/ix-cli/package.jsonindex 35b3bdf3..b4de1cab 100644--- a/ix-cli/package.json+++ b/ix-cli/package.json@@ -12,6 +12,9 @@"bin": {"ix": "dist/cli/main.js"},+ "engines": {+ "node": ">=20.0.0"+ },"scripts": {"build": "node scripts/build-core-ingestion.mjs && node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc","test": "node scripts/build-core-ingestion.mjs && vitest run --exclude test/parser.test.ts && node test/parser.smoke.mjs",diff --git a/ix-cli/src/cli/commands/ingest.ts b/ix-cli/src/cli/commands/ingest.tsindex e4b97a33..e80511bb 100644--- a/ix-cli/src/cli/commands/ingest.ts+++ b/ix-cli/src/cli/commands/ingest.ts@@ -399,7 +399,43 @@ export async function ingestFiles(? path: nodePath.resolve(resolveWorkspaceRoot(opts.root), path);+ // Workspace identity for client-agnostic backend.+ //+ // The backend used to dereference provenance.source_uri against the host+ // filesystem (via a broad HOME bind mount). We now emit workspace-relative+ // paths as the canonical source_uri, and pass a workspace_id derived from+ // the workspace root's absolute path. The backend treats both as opaque+ // strings; it never reads host files.+ const workspaceRoot = fs.statSync(resolvedPath).isDirectory()+ ? resolvedPath+ : nodePath.dirname(resolvedPath);+ const workspaceId = crypto.createHash('sha256').update(workspaceRoot).digest('hex');+ const toWorkspaceRelative = (absPath: string): string => {+ // Force workspace-local POSIX separators so IDs are stable across OS.+ const rel = nodePath.relative(workspaceRoot, absPath);+ return rel.split(nodePath.sep).join('/');+ };+const client = new IxClient(getEndpoint());++ // 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).+ const CLIENT_EXPECTED_SCHEMA_VERSION = 2;+ try {+ const health = await client.health();+ const serverVersion = (health as any)?.schema_version;+ if (typeof serverVersion === 'number' && serverVersion !== CLIENT_EXPECTED_SCHEMA_VERSION) {+ process.stderr.write(+ `\n [schema mismatch] backend schema_version=${serverVersion}, ` ++ `client expects ${CLIENT_EXPECTED_SCHEMA_VERSION}. Forcing full re-ingest.\n`,+ );+ opts.force = true;+ }+ } catch (err) {+ if (debug) process.stderr.write(`\n [schema check skipped] ${err}\n`);+ }+const start = performance.now();// Worker pool for parallel file parsing across CPU cores@@ -532,7 +568,7 @@ export async function ingestFiles(// so the cache wasn't cleared). Invalidate the cache so files are re-ingested.if (!opts.force && mtimeCache.size > 0) {const samplePaths = [...mtimeCache.keys()].slice(0, 5);- const sampleHashes = await loadExistingHashes(client, samplePaths, debug);+ const sampleHashes = await loadExistingHashes(client, samplePaths, toWorkspaceRelative, debug);if (sampleHashes.size === 0) {mtimeCache.clear();if (debug) process.stderr.write(`\n DB reset detected — invalidating mtime cache\n`);@@ -564,7 +600,7 @@ export async function ingestFiles(// Phase: hash lookup — only needed when mtime-changed files exist.let knownHashes: Map<string, string>;if (opts.force || mtimeChangedPaths.length > 0) {- knownHashes = await loadExistingHashes(client, opts.force ? filePaths : mtimeChangedPaths, debug);+ knownHashes = await loadExistingHashes(client, opts.force ? filePaths : mtimeChangedPaths, toWorkspaceRelative, debug);if (debug) process.stderr.write(`\n Source hash lookup: ${knownHashes.size} known hashes (${mtimeChangedPaths.length} mtime-changed)\n`);} else {// All files are mtime-clean — skip server round-trip entirely.@@ -751,6 +787,11 @@ export async function ingestFiles(try {let patch = buildPatchFn!(p, hash, batchEdgesByFile.get(p.filePath) ?? emptyEdges, previousHash);if (mapMode) patch = stripMapModeOps(patch);+ // Tag every patch with the workspace_id. The backend stores this+ // as an opaque attribute. The source.uri has already been set to+ // the workspace-relative path upstream in buildPatch (because we+ // passed the relative path to parseFile).+ if (patch?.source) patch.source.workspaceId = workspaceId;preparedPatches.push(makePreparedPatch(patch, j + 1, p.filePath));} catch (err) {parseErrors++;@@ -817,6 +858,8 @@ export async function ingestFiles(try {let patch = buildPatchFn!(p, hash, edgesByFile.get(p.filePath) ?? emptyEdges, previousHash);if (mapMode) patch = stripMapModeOps(patch);+ // Tag with workspace_id (see flushBatch).+ if (patch?.source) patch.source.workspaceId = workspaceId;preparedPatches.push(makePreparedPatch(patch, j + 1, p.filePath));} catch (err) {parseErrors++;@@ -877,7 +920,10 @@ export async function ingestFiles(buildPatchFn = patchBuilder.buildPatchWithResolution as Function;// Pre-filter minified files (main thread) then parse in parallel via worker pool.- const parseable: Array<{ filePath: string; source: string; hash: string; previousHash: string | undefined }> = [];+ // filePath here is the workspace-relative path (what goes to parseFile+ // and downstream into buildPatch → source_uri). absFilePath is the+ // absolute path retained for any on-disk ops (reads already happened).+ const parseable: Array<{ filePath: string; absFilePath: string; source: string; hash: string; previousHash: string | undefined }> = [];for (const { filePath, bytes, hash, previousHash } of changedPaths) {const sourceText = bytes.toString('utf-8');if (isLikelyMinifiedSource(sourceText)) {@@ -887,7 +933,11 @@ export async function ingestFiles(if (debug) process.stderr.write(`\n [skip minified-likely] ${filePath}\n`);continue;}- parseable.push({ filePath, source: sourceText, hash, previousHash });+ // parseFile receives the workspace-relative path so every+ // deterministic ID derived in buildPatch (node/edge/chunk/patch)+ // hashes relative paths. This makes graph IDs portable across+ // machines and removes backend dependence on host paths.+ parseable.push({ filePath: toWorkspaceRelative(filePath), absFilePath: filePath, source: sourceText, hash, previousHash });}progressPhase = 'Parsing';@@ -913,13 +963,23 @@ export async function ingestFiles(if (texts[j] != null) sources.set(batch[j], texts[j]!);}}- globalIndex = (ingestion.buildGlobalResolutionIndex as Function)(filePaths, sources);+ // Global resolution index is keyed on workspace-relative paths so+ // that edge resolution matches the relative paths we pass into+ // parseFile.+ const relSources = new Map<string, string>();+ for (const [abs, text] of sources) relSources.set(toWorkspaceRelative(abs), text);+ const relFilePaths = filePaths.map(toWorkspaceRelative);+ globalIndex = (ingestion.buildGlobalResolutionIndex as Function)(relFilePaths, relSources);sources.clear();+ relSources.clear();}let pendingFlush: Promise<void> = Promise.resolve();for (let i = 0; i < parseable.length; i += PARSE_STREAM_CHUNK) {const chunk = parseable.slice(i, i + PARSE_STREAM_CHUNK);+ // parseFile receives the workspace-relative path (f.filePath), so+ // every deterministic ID in the resulting patch hashes relative+ // paths. f.absFilePath is retained only for debug/error display.const parseResults = await Promise.all(chunk.map(f =>ensureParsePool().parse(f.filePath, f.source).then(r => { progressCurrent++; return r; }),@@ -948,6 +1008,8 @@ export async function ingestFiles(// Build global resolution index from all repo file paths before the parse loop// so cross-batch imports resolve correctly even in streaming per-chunk mode.// Read all Go files in parallel to maximize I/O throughput.+ // Index keys are workspace-relative to match the relative paths we pass+ // into parseFile below.{const goIndexStart = performance.now();const sources = new Map<string, string>();@@ -957,10 +1019,11 @@ export async function ingestFiles(const batch = goFiles.slice(i, i + GO_READ_CONCURRENCY);const texts = await Promise.all(batch.map(fp => fs.promises.readFile(fp, 'utf-8').catch(() => null)));for (let j = 0; j < batch.length; j++) {- if (texts[j] != null) sources.set(batch[j], texts[j]!);+ if (texts[j] != null) sources.set(toWorkspaceRelative(batch[j]), texts[j]!);}}- globalIndex = ingestion.buildGlobalResolutionIndex(filePaths, sources);+ const relFilePaths = filePaths.map(toWorkspaceRelative);+ globalIndex = ingestion.buildGlobalResolutionIndex(relFilePaths, sources);sources.clear();timings.goIndexMs = Math.round(performance.now() - goIndexStart);}@@ -981,28 +1044,32 @@ export async function ingestFiles(// Read files asynchronously and dispatch to parse pool as each file completes.// This keeps workers busy while I/O is still in flight for other files.- const readAndDispatch = chunk.map(async (filePath, idx) => {+ // fd.filePath is the workspace-relative path, which is what parseFile+ // and all downstream ID derivations see. absFilePath is kept only so+ // error messages still point at the file on disk.+ const readAndDispatch = chunk.map(async (absFilePath, idx) => {try {- const st = await fs.promises.stat(filePath);+ const st = await fs.promises.stat(absFilePath);if (st.size === 0) { filesSkipped++; return; }if (st.size > MAX_FILE_BYTES) { tooLarge++; return; }- const bytes = await fs.promises.readFile(filePath);+ const bytes = await fs.promises.readFile(absFilePath);const hash = sha256(bytes);- if (!opts.force && knownHashes.get(filePath) === hash) { filesSkipped++; return; }- const previousHash = knownHashes.get(filePath);+ if (!opts.force && knownHashes.get(absFilePath) === hash) { filesSkipped++; return; }+ const previousHash = knownHashes.get(absFilePath);const sourceText = bytes.toString('utf-8');if (isLikelyMinifiedSource(sourceText)) {minifiedLikely++;filesSkipped++;- if (debug) process.stderr.write(`\n [skip minified-likely] ${filePath}\n`);+ if (debug) process.stderr.write(`\n [skip minified-likely] ${absFilePath}\n`);return;}- const fd: NonNullable<FileData> = { filePath, source: sourceText, hash, previousHash: previousHash !== hash ? previousHash : undefined };+ const relFilePath = toWorkspaceRelative(absFilePath);+ const fd: NonNullable<FileData> = { filePath: relFilePath, source: sourceText, hash, previousHash: previousHash !== hash ? previousHash : undefined };fileData[idx] = fd;parsePromises[idx] = ensureParsePool().parse(fd.filePath, fd.source).then(r => { progressCurrent++; return r; });} catch (err) {parseErrors++;- process.stderr.write(`\n [read error] ${filePath}: ${err}\n`);+ process.stderr.write(`\n [read error] ${absFilePath}: ${err}\n`);}});await Promise.all(readAndDispatch);@@ -1142,9 +1209,32 @@ export async function ingestFiles(// Load existing hashes from the server for change detection// ----------------------------------------------------------------------------async function loadExistingHashes(client: IxClient, filePaths: string[], debug = false): Promise<Map<string, string>> {+// The backend now stores workspace-relative source_uri values. The CLI still+// tracks files internally by absolute path (needed for fs reads), so this+// helper converts to relative before the wire call and maps the server's+// response back onto the caller's absolute keys.+async function loadExistingHashes(+ client: IxClient,+ filePaths: string[],+ toRelative: (absPath: string) => string,+ debug = false,+): Promise<Map<string, string>> {try {- return await client.getSourceHashes(filePaths);+ const relPaths: string[] = new Array(filePaths.length);+ const relToAbs = new Map<string, string>();+ for (let i = 0; i < filePaths.length; i++) {+ const abs = filePaths[i];+ const rel = toRelative(abs);+ relPaths[i] = rel;+ relToAbs.set(rel, abs);+ }+ const serverHashes = await client.getSourceHashes(relPaths);+ const out = new Map<string, string>();+ for (const [rel, hash] of serverHashes) {+ const abs = relToAbs.get(rel);+ if (abs !== undefined) out.set(abs, hash);+ }+ return out;} catch (err) {if (debug) process.stderr.write(`\n [hash lookup failed] ${err}\n`);return new Map();diff --git a/ix-cli/src/cli/commands/map.ts b/ix-cli/src/cli/commands/map.tsindex bc2f648b..6dff0703 100644--- a/ix-cli/src/cli/commands/map.ts+++ b/ix-cli/src/cli/commands/map.ts@@ -5,6 +5,7 @@ import { IxClient } from "../../client/api.js";import { getEndpoint } from "../config.js";import { roundFloat } from "../format.js";import { bootstrap } from "../bootstrap.js";+import { formatFetchError } from "../errors.js";import { ingestFiles } from "./ingest.js";export interface MapRegion {@@ -159,7 +160,7 @@ Examples:mapMode: true,});} catch (err: any) {- console.error(chalk.red("Error:"), err.message ?? err);+ console.error(chalk.red("Error:"), formatFetchError(err));process.exitCode = 1;return;}@@ -183,7 +184,7 @@ Examples:result = await client.map({ full: opts.full }) as MapResult;} catch (err: any) {if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }- console.error(chalk.red("Error:"), err.message ?? err);+ console.error(chalk.red("Error:"), formatFetchError(err));process.exitCode = 1;return;}diff --git a/ix-cli/src/cli/commands/read.ts b/ix-cli/src/cli/commands/read.tsindex bf2d9797..e0ad77f3 100644--- a/ix-cli/src/cli/commands/read.ts+++ b/ix-cli/src/cli/commands/read.ts@@ -3,7 +3,7 @@ import * as path from "node:path";import type { Command } from "commander";import chalk from "chalk";import { IxClient } from "../../client/api.js";-import { getEndpoint, resolveWorkspaceRoot } from "../config.js";+import { absoluteFromSourceUri, getEndpoint, resolveWorkspaceRoot } from "../config.js";import { resolveEntityFull } from "../resolve.js";import { stderr } from "../stderr.js";import { isFileStale } from "../stale.js";@@ -181,19 +181,23 @@ Examples:const symbolResult = await trySymbolMatch(client, rawTarget, { kind: opts.kind, path: opts.path, pick: opts.pick ? parseInt(opts.pick, 10) : undefined });if (symbolResult.type === "resolved") {const { node, sourceUri } = symbolResult;- const stale = sourceUri ? await checkStale(client, sourceUri) : false;+ // sourceUri coming from the graph is workspace-relative under the+ // client-agnostic backend. Resolve it against the active workspace+ // root before any fs call.+ const absSourceUri = sourceUri ? absoluteFromSourceUri(sourceUri, opts.root) : null;+ const stale = absSourceUri ? await checkStale(client, absSourceUri) : false;// If the source file exists, extract the symbol's lines- if (sourceUri && fs.existsSync(sourceUri)) {+ if (absSourceUri && fs.existsSync(absSourceUri)) {const lineStart = node.attrs?.lineStart ?? node.attrs?.line_start ?? 1;const lineEnd = node.attrs?.lineEnd ?? node.attrs?.line_end;- const fileContent = fs.readFileSync(sourceUri, "utf-8");+ const fileContent = fs.readFileSync(absSourceUri, "utf-8");const allLines = fileContent.split("\n");const effectiveEnd = lineEnd ?? allLines.length;const content = allLines.slice(lineStart - 1, effectiveEnd).join("\n");const result: ReadResult = {targetType: "symbol",- path: sourceUri,+ path: absSourceUri,lineStart,lineEnd: effectiveEnd,content,@@ -211,7 +215,7 @@ Examples:const lines = String(attrContent).split("\n");const result: ReadResult = {targetType: "symbol",- path: sourceUri ?? "(no source file)",+ path: absSourceUri ?? sourceUri ?? "(no source file)",lineStart: 1,lineEnd: lines.length,content: String(attrContent),@@ -223,7 +227,7 @@ Examples:return;}- stderr(`Source file not found for symbol: ${node.name} (${sourceUri ?? "no provenance"})`);+ stderr(`Source file not found for symbol: ${node.name} (${absSourceUri ?? sourceUri ?? "no provenance"})`);return;}diff --git a/ix-cli/src/cli/commands/view.ts b/ix-cli/src/cli/commands/view.tsindex fb6e5131..c9e773c8 100644--- a/ix-cli/src/cli/commands/view.ts+++ b/ix-cli/src/cli/commands/view.ts@@ -10,6 +10,7 @@ import {import { join, dirname } from "path";import { homedir, platform } from "os";import { fileURLToPath } from "url";+import { createConnection } from "net";const IX_HOME = process.env.IX_HOME || join(homedir(), ".ix");const PID_FILE = join(IX_HOME, "compass.pid");@@ -44,6 +45,18 @@ function readAlivePid(): number | null {}}+/** 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));+ });+}+/** Generate the inline server script that serves static files + proxies /v1. */function serverScript(distDir: string, port: number): string {return `@@ -147,15 +160,15 @@ function openBrowser(url: string): void {export function registerViewCommand(program: Command): void {const view = program.command("view")- .description("Open the Ix System Compass visualizer");+ .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("--port <port>", "Port to serve on", "8080").option("--no-open", "Don't auto-open browser")- .action((opts) => {- const port = parseInt(opts.port, 10);+ .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);@@ -168,6 +181,13 @@ export function registerViewCommand(program: Command): void {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.");diff --git a/ix-cli/src/cli/config.ts b/ix-cli/src/cli/config.tsindex dc85155c..20f06bb3 100644--- a/ix-cli/src/cli/config.ts+++ b/ix-cli/src/cli/config.ts@@ -74,6 +74,21 @@ export function getActiveWorkspaceRoot(): string | undefined {return getDefaultWorkspace()?.root_path;}+// Resolve a source_uri from the graph (which is now a workspace-relative+// POSIX path under the client-agnostic backend design) back to an absolute+// host filesystem path. If the input is already absolute (e.g. legacy graphs+// or external absolute paths), it is returned as-is. Used by any command that+// needs to actually open a file off disk (ix read, ix explain, ...).+export function absoluteFromSourceUri(sourceUri: string, explicitRoot?: string): string {+ if (!sourceUri) return sourceUri;+ // Treat both POSIX abs (`/`) and Windows abs (`C:\`) as already resolved.+ if (sourceUri.startsWith("/") || /^[A-Za-z]:[\\/]/.test(sourceUri)) return sourceUri;+ const root = resolveWorkspaceRoot(explicitRoot);+ // POSIX-normalize the relative segment before joining.+ const normalized = sourceUri.replace(/\\/g, "/");+ return require("node:path").resolve(root, normalized);+}+export function resolveWorkspaceRoot(explicitRoot?: string): string {// 1. Explicit --rootif (explicitRoot) return explicitRoot;diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.tsindex 5d73eddc..9889ce16 100644--- a/ix-cli/src/cli/errors.ts+++ b/ix-cli/src/cli/errors.ts@@ -70,6 +70,39 @@ export class CliResolutionError extends Error {}}+/**+ * Format an error for display, unwrapping fetch `TypeError: fetch failed`+ * to expose the underlying transport cause (e.g. ECONNRESET, UND_ERR_SOCKET).+ *+ * Node's built-in fetch (undici) throws `TypeError('fetch failed')` on any+ * transport-level failure and stashes the real error in `err.cause`. Without+ * this unwrap, users see a bare "fetch failed" with no actionable detail —+ * see the Node 18 EOL / undici 5.x transport-drop bug report.+ */+export function formatFetchError(err: unknown): string {+ if (err === null || err === undefined) return String(err);+ const e = err as { message?: unknown; cause?: unknown };+ const base = typeof e.message === "string" && e.message.length > 0+ ? e.message+ : String(err);++ if (base.toLowerCase().includes("fetch failed") && e.cause) {+ const cause = e.cause as { code?: unknown; message?: unknown };+ const parts: string[] = [];+ if (typeof cause.code === "string" && cause.code.length > 0) {+ parts.push(cause.code);+ }+ if (typeof cause.message === "string" && cause.message.length > 0) {+ parts.push(cause.message);+ } else if (parts.length === 0) {+ parts.push(String(e.cause));+ }+ return `${base} (${parts.join(": ")})`;+ }++ return base;+}+export function renderCliError(err: unknown, debug = false): void {if (err instanceof CliUsageError || err instanceof CliResolutionError) {process.stderr.write(chalk.red(`Error: ${err.message}\n`));diff --git a/ix-cli/src/cli/format.ts b/ix-cli/src/cli/format.tsindex e579c350..e6743f74 100644--- a/ix-cli/src/cli/format.ts+++ b/ix-cli/src/cli/format.ts@@ -5,9 +5,17 @@ export type ResultSource = "graph" | "text" | "graph+text" | "heuristic";// ── JSON optimization helpers ──────────────────────────────────────────────-/** Strip the cwd prefix from absolute paths to save tokens in JSON output. */+/**+ * Strip the cwd prefix from absolute paths to save tokens in JSON output.+ *+ * Under the client-agnostic backend design, source_uri values are already+ * workspace-relative. For those we return the input unchanged. Legacy absolute+ * paths (e.g. from older graphs) are still handled the old way.+ */export function relativePath(absPath: string | undefined | null): string | undefined {if (!absPath) return undefined;+ // Already relative (workspace-relative path from post-migration graphs).+ if (!absPath.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(absPath)) return absPath;const cwd = process.cwd();if (absPath.startsWith(cwd + "/")) return absPath.slice(cwd.length + 1);// Also handle /Users/.../project/ style without trailing slash matchdiff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.tsindex b8415758..56481f57 100644--- a/ix-cli/src/cli/main.ts+++ b/ix-cli/src/cli/main.ts@@ -9,6 +9,22 @@ import { readFileSync } from "fs";import { join, dirname } from "path";import { fileURLToPath } from "url";+// Runtime Node version guard. Runs before any command work so users on an+// unsupported Node get an actionable message instead of a cryptic "fetch+// failed" deep inside undici.+const MIN_NODE_MAJOR = 20;+{+ const current = process.versions.node;+ const major = parseInt(current.split(".")[0] ?? "0", 10);+ if (!Number.isFinite(major) || major < MIN_NODE_MAJOR) {+ process.stderr.write(+ `Ix requires Node.js ${MIN_NODE_MAJOR} or newer. You are running v${current}.\n` ++ `Install a supported version from https://nodejs.org/ and re-run.\n`+ );+ process.exit(1);+ }+}+let cliVersion = "0.0.0";try {const __dirname = dirname(fileURLToPath(import.meta.url));diff --git a/ix-cli/src/client/types.ts b/ix-cli/src/client/types.tsindex a41fb0f5..e78f209b 100644--- a/ix-cli/src/client/types.ts+++ b/ix-cli/src/client/types.ts@@ -150,13 +150,25 @@ export interface IngestResult {export interface HealthResponse {status: string;+ // Backend on-disk graph format version. When a client's expected version+ // differs from this, it forces a clean re-ingest (e.g. absolute→relative+ // source_uri migration changes every node ID).+ schema_version?: number;}export interface PatchSource {+ // uri is the provenance source URI. In the client-agnostic backend design it+ // is a workspace-relative path (POSIX separators), not an absolute host path.+ // The backend treats this as an opaque string key for joins/tombstones.uri: string;sourceHash?: string;extractor: string;sourceType: string;+ // workspaceId uniquely identifies the workspace whose files produced this+ // patch. Derived client-side as SHA-256 of the workspace root's absolute+ // path. Backend stores it as an opaque attribute for future multi-workspace+ // disambiguation; it does not interpret the value.+ workspaceId?: string;}export interface PatchOp {diff --git a/requirements.txt b/requirements.txtindex 5e5d8513..a341cd2e 100644--- a/requirements.txt+++ b/requirements.txt@@ -29,11 +29,11 @@ git>=2# STEP 1: Node.js (auto-installed/upgraded if missing or too old)# ============================================================================-# Node.js >= 18 (installer targets Node 22 LTS)+# Node.js >= 20 (installer targets Node 22 LTS)# macOS: brew install node OR official .pkg installer# Linux: NodeSource apt/dnf/yum repo (setup_22.x) OR apk# Windows: manual from https://nodejs.org/-node>=18+node>=20npm>=8 # bundled with Node.js# ============================================================================diff --git a/scripts/backend.sh b/scripts/backend.shindex 56873d34..effc4938 100755--- a/scripts/backend.sh+++ b/scripts/backend.sh@@ -21,23 +21,12 @@ set -euo pipefailIX_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"cd "$IX_DIR"-# On Windows/MINGW, Docker Compose (a Windows binary) can mix POSIX and Windows-# home paths if we rely on nested interpolation defaults in the compose file.-# Export both sides of the bind mount explicitly instead:-# IX_HOST_MOUNT_ROOT → host bind source (cygpath -m: C:/Users/...)-# IX_CONTAINER_MOUNT_ROOT → container target ($HOME: /c/Users/... or /Users/...)-# The dc() helper passes -f with a Windows-format path so docker compose can-# locate its file regardless of how it resolves the CWD from a MINGW shell.if [[ "$(uname -s)" =~ MINGW|MSYS|CYGWIN ]]; then- export IX_HOST_MOUNT_ROOT="$(cygpath -m "$HOME")"- export IX_CONTAINER_MOUNT_ROOT="${HOME}"dc() {MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*' \docker compose -f "$(cygpath -m "$IX_DIR/$COMPOSE_FILE")" "$@"}else- export IX_HOST_MOUNT_ROOT="${HOME}"- export IX_CONTAINER_MOUNT_ROOT="${HOME}"dc() { docker compose -f "$COMPOSE_FILE" "$@"; }fidiff --git a/scripts/build-cli.sh b/scripts/build-cli.shindex e1a46adb..a1ab8f5c 100755--- a/scripts/build-cli.sh+++ b/scripts/build-cli.sh@@ -20,13 +20,13 @@ CLI_DIR="$IX_DIR/ix-cli"check_prerequisites() {if ! command -v node &> /dev/null; thenecho "Error: Node.js is not installed."- echo " Install: https://nodejs.org/ (v18+ required)"+ echo " Install: https://nodejs.org/ (v20+ required)"exit 1fiNODE_VERSION=$(node -v | sed 's/v//' | cut -d. -f1)- if [ "$NODE_VERSION" -lt 18 ]; then- echo "Error: Node.js 18+ required (found $(node -v))"+ if [ "$NODE_VERSION" -lt 20 ]; then+ echo "Error: Node.js 20+ required (found $(node -v))"exit 1fidiff --git a/scripts/dev/setup.sh b/scripts/dev/setup.shindex 92d85113..4a9796d6 100755--- a/scripts/dev/setup.sh+++ b/scripts/dev/setup.sh@@ -129,7 +129,7 @@ if [ "${#MISSING_DEPS[@]}" -gt 0 ]; thenfor dep in "${MISSING_DEPS[@]}"; docase "$dep" indocker) echo " docker: https://docs.docker.com/get-docker/" ;;- node) echo " node: https://nodejs.org (v18+ required)" ;;+ node) echo " node: https://nodejs.org (v20+ required)" ;;esacdoneecho ""diff --git a/scripts/dev/shutdown.sh b/scripts/dev/shutdown.shindex 5954fc29..8f0baeb2 100755--- a/scripts/dev/shutdown.sh+++ b/scripts/dev/shutdown.sh@@ -21,15 +21,11 @@ cd "$IX_DIR"COMPOSE_FILE="docker-compose.standalone.yml"if [[ "$(uname -s)" =~ MINGW|MSYS|CYGWIN ]]; then- export IX_HOST_MOUNT_ROOT="$(cygpath -m "$HOME")"- export IX_CONTAINER_MOUNT_ROOT="${HOME}"dc() {MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*' \docker compose -f "$(cygpath -m "$IX_DIR/$COMPOSE_FILE")" "$@"}else- export IX_HOST_MOUNT_ROOT="${HOME}"- export IX_CONTAINER_MOUNT_ROOT="${HOME}"dc() { docker compose -f "$IX_DIR/$COMPOSE_FILE" "$@"; }fidiff --git a/scripts/install/install.ps1 b/scripts/install/install.ps1index bd1172e6..c964dab7 100644--- a/scripts/install/install.ps1+++ b/scripts/install/install.ps1@@ -27,7 +27,7 @@ $IxBin = "$IxHome\bin"$ComposeDir = "$IxHome\backend"$HealthUrl = "http://localhost:8090/v1/health"$ArangoUrl = "http://localhost:8529/_api/version"-$NodeMinMajor = 18+$NodeMinMajor = 20# ── Helpers ──────────────────────────────────────────────────────────────────diff --git a/scripts/install/install.sh b/scripts/install/install.shindex 1d90f2e1..71e85ac0 100755--- a/scripts/install/install.sh+++ b/scripts/install/install.sh@@ -28,20 +28,15 @@ COMPOSE_DIR="$IX_HOME/backend"HEALTH_URL="http://localhost:8090/v1/health"ARANGO_URL="http://localhost:8529/_api/version"-NODE_MIN_MAJOR=18+NODE_MIN_MAJOR=20# -- Windows / POSIX docker compose wrapper ---+#case "$(uname -s)" inMINGW*|MSYS*|CYGWIN*)- IX_HOST_MOUNT_ROOT="$(cygpath -m "$HOME")"- export IX_HOST_MOUNT_ROOT- export IX_CONTAINER_MOUNT_ROOT="${HOME}"dc() { MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*' docker compose "$@"; };;*)- export IX_HOST_MOUNT_ROOT="${HOME}"- export IX_CONTAINER_MOUNT_ROOT="${HOME}"dc() { docker compose "$@"; };;esac