Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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.yml
index 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/" || true
cat > "$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/" || true
cat > "$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/" || true
cat > "$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/" || true
cat > "$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/" || true
cat > "$STAGING/ix.cmd" <<'WRAPPER'
@echo off
diff --git a/README.md b/README.md
index 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.ts
index 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.yml
index a6734a18..04cb048d 100644
--- a/docker-compose.standalone.yml
+++ b/docker-compose.standalone.yml
@@ -30,11 +30,6 @@ services:
- backend
ports:
- "127.0.0.1:8090:8090"
- volumes:
- - type: bind
- source: ${IX_HOST_MOUNT_ROOT:-$HOME}
- target: ${IX_CONTAINER_MOUNT_ROOT:-$HOME}
- read_only: true
environment:
ARANGO_HOST: arangodb
ARANGO_PORT: "8529"
diff --git a/ix-cli/package.json b/ix-cli/package.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 --root
if (explicitRoot) return explicitRoot;
diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.ts
index 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.ts
index 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 match
diff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.ts
index 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.ts
index 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.txt
index 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>=20
npm>=8 # bundled with Node.js
# ============================================================================
diff --git a/scripts/backend.sh b/scripts/backend.sh
index 56873d34..effc4938 100755
--- a/scripts/backend.sh
+++ b/scripts/backend.sh
@@ -21,23 +21,12 @@ set -euo pipefail
IX_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" "$@"; }
fi
diff --git a/scripts/build-cli.sh b/scripts/build-cli.sh
index 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; then
echo "Error: Node.js is not installed."
- echo " Install: https://nodejs.org/ (v18+ required)"
+ echo " Install: https://nodejs.org/ (v20+ required)"
exit 1
fi
NODE_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 1
fi
diff --git a/scripts/dev/setup.sh b/scripts/dev/setup.sh
index 92d85113..4a9796d6 100755
--- a/scripts/dev/setup.sh
+++ b/scripts/dev/setup.sh
@@ -129,7 +129,7 @@ if [ "${#MISSING_DEPS[@]}" -gt 0 ]; then
for dep in "${MISSING_DEPS[@]}"; do
case "$dep" in
docker) echo " docker: https://docs.docker.com/get-docker/" ;;
- node) echo " node: https://nodejs.org (v18+ required)" ;;
+ node) echo " node: https://nodejs.org (v20+ required)" ;;
esac
done
echo ""
diff --git a/scripts/dev/shutdown.sh b/scripts/dev/shutdown.sh
index 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" "$@"; }
fi
diff --git a/scripts/install/install.ps1 b/scripts/install/install.ps1
index 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.sh
index 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)" in
MINGW*|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