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
fix(config): honour IX_HOME for config, the workspace registry and caches (#666)
Ian Hock14b38ec32fd8
diff --git a/docs/api/README.md b/docs/api/README.mdindex a2f9dad7..34d0f0a7 100644--- a/docs/api/README.md+++ b/docs/api/README.md@@ -377,7 +377,7 @@ count rather than every skip, and `skipReasons.emptyFile`, previously hardcoded|---|---|---|| `IX_STITCH_COOLDOWN_MS` | `900000` | How long to hold off after a stitch that did not prove it stopped, measured from when the attempt ended. `0` disables the cooldown; single-flight stays. Values under ~2 min are not honoured after a killed process — see above. || `IX_STITCH_WAIT_MS` | `30000` | How long to wait for an in-flight stitch before skipping. `0` sheds immediately. |-| `IX_LOCK_DIR` | `~/.ix/locks` | Where the stitch lock and cooldown record live (shared with the map lock). `ix reset` clears the cooldown, so the full re-ingest that follows one is not refused by it. |+| `IX_LOCK_DIR` | `$IX_HOME/locks` (`~/.ix/locks` by default) | Where the stitch lock and cooldown record live (shared with the map lock). `ix reset` clears the cooldown, so the full re-ingest that follows one is not refused by it. || `IX_MAP_LOCK_MAX_MS` | `1200000` | Shared with the map lock: how old a held lock must be before it is presumed abandoned and stolen. Lowering it to a few seconds so a wedged `ix map` self-heals faster also lets a second process steal the stitch lock from an in-flight stitch. The cooldown normally catches that on the next read, so it only matters together with `IX_STITCH_COOLDOWN_MS=0` — which is the one case where "single-flight stays" stops being true. |This bounds the client. Cancelling the server-side query when the client hangsdiff --git a/docs/prerequisites.md b/docs/prerequisites.mdindex dfd83fca..a213e617 100644--- a/docs/prerequisites.md+++ b/docs/prerequisites.md@@ -134,11 +134,17 @@ ripgrep>=13# DIRECTORIES CREATED# ============================================================================-# ~/.ix/ Ix home directory+# ~/.ix/ Ix home directory (override with $IX_HOME)# ~/.ix/config.yaml CLI configuration# ~/.ix/backend/ Docker Compose file for local backend# ~/.ix/cli/ Installed CLI binary + node_modules#+# $IX_HOME relocates ALL of the above, configuration included. Set it to give a+# harness, a CI job or a second install its own state instead of sharing yours.+# Note it is read at use, not at install: exporting it after an install points+# the CLI at an empty directory, so move ~/.ix there (or unset it) rather than+# expecting the old configuration to be found.+## Wrapper: /usr/local/bin/ix (if writable) or ~/.local/bin/ix (fallback)# Ports: 8090 (Memory Layer), 8529 (ArangoDB) — localhost only```diff --git a/ix-cli/src/cli/__tests__/config-file-mode.test.ts b/ix-cli/src/cli/__tests__/config-file-mode.test.tsindex dd36b700..f25dc58a 100644--- a/ix-cli/src/cli/__tests__/config-file-mode.test.ts+++ b/ix-cli/src/cli/__tests__/config-file-mode.test.ts@@ -6,22 +6,30 @@ import { parse } from "yaml";import { saveConfig } from "../config.js";-// Isolate ~/.ix by pointing HOME/USERPROFILE at a temp dir per test.+// Isolate the Ix state directory with IX_HOME, deliberately NOT with HOME.+//+// This file used to override HOME/USERPROFILE, which worked only because+// `os.homedir()` happens to read $HOME on POSIX under vitest's default (forks)+// pool. Under `--pool=threads` a worker's `process.env` write never reaches the+// environment libuv reads, so `homedir()` returned the developer's REAL home+// and every `saveConfig` below wrote their actual ~/.ix/config.yaml -- and+// since `workspaces` is an OSS-owned key, the config object these tests pass+// (which has none) DELETED their whole workspace registry. The six failing+// assertions were the only warning. `process.env.IX_HOME` is read off the+// object by `ixHome()`, so it isolates under either pool.let home: string;-let savedHome: string | undefined;-let savedProfile: string | undefined;+let savedIxHome: string | undefined;beforeEach(() => {home = fs.mkdtempSync(nodePath.join(os.tmpdir(), "ix-cfgmode-"));- savedHome = process.env.HOME;- savedProfile = process.env.USERPROFILE;- process.env.HOME = home;- process.env.USERPROFILE = home;+ savedIxHome = process.env.IX_HOME;+ // A path that does not exist yet: the first test asserts saveConfig creates it.+ process.env.IX_HOME = nodePath.join(home, ".ix");});afterEach(() => {- process.env.HOME = savedHome;- process.env.USERPROFILE = savedProfile;+ if (savedIxHome === undefined) delete process.env.IX_HOME;+ else process.env.IX_HOME = savedIxHome;try { fs.rmSync(home, { recursive: true, force: true }); } catch { /* ignore */ }});diff --git a/ix-cli/src/cli/__tests__/ix-home.test.ts b/ix-cli/src/cli/__tests__/ix-home.test.tsnew file mode 100644index 00000000..eaa39fad--- /dev/null+++ b/ix-cli/src/cli/__tests__/ix-home.test.ts@@ -0,0 +1,156 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import * as fs from "node:fs";+import * as os from "node:os";+import * as nodePath from "node:path";+import { parse } from "yaml";++import { ixHome } from "../ix-home.js";+import { ingestMtimeCachePath, mapBaselinePath, saveConfig, stitchScopeCachePath } from "../config.js";+import { ensureLocalConfig } from "../bootstrap.js";++// IX_HOME, not HOME. `os.homedir()` answers from the process environment that+// libuv sees, which a worker thread's `process.env` write never reaches -- so a+// HOME override silently does nothing under vitest's threads pool while+// `process.env.IX_HOME` is read straight off the object and works in either.+let home: string;+let savedIxHome: string | undefined;++beforeEach(() => {+ home = fs.mkdtempSync(nodePath.join(os.tmpdir(), "ix-home-"));+ savedIxHome = process.env.IX_HOME;+ process.env.IX_HOME = home;+});++afterEach(() => {+ if (savedIxHome === undefined) delete process.env.IX_HOME;+ else process.env.IX_HOME = savedIxHome;+ try { fs.rmSync(home, { recursive: true, force: true }); } catch { /* ignore */ }+});++describe("ixHome", () => {+ it("is IX_HOME when set", () => {+ expect(ixHome()).toBe(home);+ });++ it("falls back to ~/.ix when IX_HOME is unset", () => {+ delete process.env.IX_HOME;+ expect(ixHome()).toBe(nodePath.join(os.homedir(), ".ix"));+ });++ it("is re-read on every call, so a module imported earlier still sees a change", () => {+ const first = ixHome();+ const second = fs.mkdtempSync(nodePath.join(os.tmpdir(), "ix-home-2-"));+ process.env.IX_HOME = second;+ try {+ expect(ixHome()).toBe(second);+ expect(ixHome()).not.toBe(first);+ } finally {+ process.env.IX_HOME = home;+ fs.rmSync(second, { recursive: true, force: true });+ }+ });+});++describe("state that follows IX_HOME", () => {+ // The regression this file exists for: every one of these used a bare+ // `homedir()`, so setting IX_HOME isolated the CLI install and nothing else.+ // A benchmark harness that set it still read its endpoint from, and+ // registered its throwaway worktrees in, the developer's real ~/.ix.+ it("writes config.yaml under IX_HOME, not under the real home", () => {+ // Snapshot the real file (or its absence) so "nothing landed there" is a+ // comparison, not a guess about a filename that is never written.+ const real = nodePath.join(os.homedir(), ".ix", "config.yaml");+ const readReal = () => (fs.existsSync(real) ? fs.readFileSync(real, "utf8") : null);+ const before = readReal();++ saveConfig({ endpoint: "http://ix-home.example", format: "json" });++ const written = nodePath.join(home, "config.yaml");+ expect(fs.existsSync(written)).toBe(true);+ expect(parse(fs.readFileSync(written, "utf8"))).toMatchObject({+ endpoint: "http://ix-home.example",+ format: "json",+ });+ expect(readReal()).toBe(before);+ });++ it("keeps the 0700 directory / 0600 file guarantees under IX_HOME", () => {+ if (process.platform === "win32") return; // POSIX bits are meaningless there+ const nested = nodePath.join(home, "nested");+ process.env.IX_HOME = nested;+ saveConfig({ endpoint: "http://localhost:8090", format: "text" });+ expect(fs.statSync(nested).mode & 0o777).toBe(0o700);+ expect(fs.statSync(nodePath.join(nested, "config.yaml")).mode & 0o777).toBe(0o600);+ });++ it("puts the per-project caches under IX_HOME", () => {+ for (const p of [ingestMtimeCachePath("/tmp/project"), mapBaselinePath("/tmp/project"),+ stitchScopeCachePath("ws-1")]) {+ expect(nodePath.dirname(p)).toBe(home);+ }+ });+});++describe("ensureLocalConfig under IX_HOME", () => {+ // These need a fake "real" home with a legacy ~/.ix/config.yaml in it. A+ // HOME/USERPROFILE override is honoured by os.homedir() under vitest's+ // default forks pool only, so each test checks it took and otherwise returns+ // rather than asserting against the developer's actual home.+ let fakeHome: string;+ let savedHome: string | undefined;+ let savedProfile: string | undefined;++ beforeEach(() => {+ fakeHome = fs.mkdtempSync(nodePath.join(os.tmpdir(), "ix-home-legacy-"));+ savedHome = process.env.HOME;+ savedProfile = process.env.USERPROFILE;+ process.env.HOME = fakeHome;+ process.env.USERPROFILE = fakeHome;+ });++ afterEach(() => {+ process.env.HOME = savedHome;+ process.env.USERPROFILE = savedProfile;+ vi.restoreAllMocks();+ try { fs.rmSync(fakeHome, { recursive: true, force: true }); } catch { /* ignore */ }+ });++ it("names the untouched legacy ~/.ix/config.yaml when it creates a fresh config under IX_HOME", () => {+ if (os.homedir() !== fakeHome) return;+ const legacy = nodePath.join(fakeHome, ".ix", "config.yaml");+ fs.mkdirSync(nodePath.dirname(legacy), { recursive: true });+ fs.writeFileSync(legacy, "endpoint: http://legacy.example\nformat: text\n");+ const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);++ expect(ensureLocalConfig()).toBe(true);++ const said = write.mock.calls.map(c => String(c[0])).join("");+ expect(said).toContain("IX_HOME is set");+ expect(said).toContain(nodePath.join(home, "config.yaml"));+ expect(said).toContain(legacy);+ // Told about, not touched.+ expect(fs.readFileSync(legacy, "utf8")).toBe("endpoint: http://legacy.example\nformat: text\n");+ // And the new file is the default one, not a copy.+ expect(parse(fs.readFileSync(nodePath.join(home, "config.yaml"), "utf8"))).not.toMatchObject({+ endpoint: "http://legacy.example",+ });+ });++ it("says nothing when there is no legacy config to point at", () => {+ if (os.homedir() !== fakeHome) return;+ const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);+ expect(ensureLocalConfig()).toBe(true);+ expect(write.mock.calls.map(c => String(c[0])).join("")).not.toContain("IX_HOME is set");+ });++ it("says nothing on the second call, because the file already exists", () => {+ if (os.homedir() !== fakeHome) return;+ const legacy = nodePath.join(fakeHome, ".ix", "config.yaml");+ fs.mkdirSync(nodePath.dirname(legacy), { recursive: true });+ fs.writeFileSync(legacy, "endpoint: http://legacy.example\n");+ expect(ensureLocalConfig()).toBe(true);+ const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);+ expect(ensureLocalConfig()).toBe(false);+ expect(write).not.toHaveBeenCalled();+ });+});diff --git a/ix-cli/src/cli/bootstrap.ts b/ix-cli/src/cli/bootstrap.tsindex 720f9a93..74d12d14 100644--- a/ix-cli/src/cli/bootstrap.ts+++ b/ix-cli/src/cli/bootstrap.ts@@ -1,4 +1,4 @@-import { mkdirSync, writeFileSync } from "node:fs";+import { existsSync, mkdirSync, writeFileSync } from "node:fs";import { join, basename, resolve } from "node:path";import { homedir } from "node:os";import { execFileSync } from "node:child_process";@@ -6,6 +6,8 @@ import chalk from "chalk";import { IxClient } from "../client/api.js";import { renderBanner } from "./banner.js";import { canonicalWorkspacePath, getEndpoint, loadConfig, saveConfig, findWorkspaceForCwd, getDefaultWorkspace, type WorkspaceConfig } from "./config.js";+import { ixHome } from "./ix-home.js";+import { stderr } from "./stderr.js";import { workspaceIdForPath } from "./system.js";import { readBackendHealth } from "./commands/upgrade.js";@@ -16,17 +18,18 @@ export interface BootstrapResult {}/**- * Ensure ~/.ix/config.yaml exists. Creates it silently if missing.- * Returns true if it was just created.+ * Ensure `$IX_HOME/config.yaml` (default `~/.ix/config.yaml`) exists. Creates+ * it silently if missing. Returns true if it was just created.*/export function ensureLocalConfig(): boolean {- const configDir = join(homedir(), ".ix");+ const configDir = ixHome();const configPath = join(configDir, "config.yaml");mkdirSync(configDir, { recursive: true });try {// 'wx' creates the file atomically and throws EEXIST if it already exists,// avoiding the existsSync-then-write TOCTOU (CodeQL js/file-system-race).writeFileSync(configPath, `endpoint: ${getEndpoint()}\nformat: text\n`, { flag: "wx" });+ noteRelocatedConfig(configPath);return true;} catch (err: any) {if (err?.code === "EEXIST") return false;@@ -34,6 +37,27 @@ export function ensureLocalConfig(): boolean {}}+/**+ * A config was just created under `$IX_HOME` while a `~/.ix/config.yaml`+ * exists. That is the one user-visible consequence of config following+ * IX_HOME: someone who exported it as a custom install root before config+ * honoured it now finds the CLI on the default endpoint with no workspaces,+ * and nothing else says why. Say why, on stderr, at the moment it happens --+ * which is exactly once, because the file is created exactly once.+ *+ * Nothing is migrated automatically: two live copies of a credential-bearing+ * file is worse than one clear message about which one is in use.+ */+function noteRelocatedConfig(configPath: string): void {+ if (!process.env.IX_HOME) return;+ const legacy = join(homedir(), ".ix", "config.yaml");+ if (legacy === configPath || !existsSync(legacy)) return;+ stderr(chalk.yellow(+ `IX_HOME is set: using ${configPath}. Your existing ${legacy} was not migrated -- ` ++ `copy it there, or unset IX_HOME to keep using it.`,+ ));+}+// Roots whose workspace_id was re-keyed to the path-based id during THIS process,// mapped to the OLD (pre-migration) id. getOrCreateWorkspace is called more than once// per `ix map` (bootstrap() registers, then ingest resolves the id); the first calldiff --git a/ix-cli/src/cli/config.ts b/ix-cli/src/cli/config.tsindex 2a6ca750..2df66178 100644--- a/ix-cli/src/cli/config.ts+++ b/ix-cli/src/cli/config.ts@@ -1,10 +1,10 @@import { readFileSync, writeFileSync, existsSync, rmSync, chmodSync, renameSync, realpathSync, mkdirSync } from "node:fs";import { isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";-import { homedir } from "node:os";import { createHash } from "node:crypto";import { execFileSync } from "node:child_process";import { parse, stringify } from "yaml";import { IxClient } from "../client/api.js";+import { ixHome } from "./ix-home.js";/*** Path to the per-project ingest mtime cache (the "skip unchanged files on re-map"@@ -13,13 +13,13 @@ import { IxClient } from "../client/api.js";*/export function ingestMtimeCachePath(projectRoot: string): string {const key = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);- return join(homedir(), ".ix", `ingest_mtimes_${key}.json`);+ return join(ixHome(), `ingest_mtimes_${key}.json`);}/** Path to the architecture-map completion marker for one project root. */export function mapBaselinePath(projectRoot: string): string {const key = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);- return join(homedir(), ".ix", `map_baseline_${key}.json`);+ return join(ixHome(), `map_baseline_${key}.json`);}/**@@ -30,7 +30,7 @@ export function mapBaselinePath(projectRoot: string): string {*/export function stitchScopeCachePath(workspaceId: string): string {const key = createHash("sha256").update(workspaceId).digest("hex").slice(0, 12);- return join(homedir(), ".ix", `stitch_scope_${key}.json`);+ return join(ixHome(), `stitch_scope_${key}.json`);}/**@@ -64,7 +64,7 @@ export function readStitchScope(workspaceId: string): { systemId: string | nullexport function writeStitchScope(workspaceId: string, systemId: string | null): void {try {const path = stitchScopeCachePath(workspaceId);- mkdirSync(join(homedir(), ".ix"), { recursive: true });+ mkdirSync(ixHome(), { recursive: true });writeFileSync(path, JSON.stringify({ workspaceId, systemId }) + "\n", "utf8");} catch { /* non-critical */ }}@@ -110,7 +110,7 @@ const defaultConfig: IxConfig = {};export function loadConfig(): IxConfig {- const configPath = join(homedir(), ".ix", "config.yaml");+ const configPath = join(ixHome(), "config.yaml");if (!existsSync(configPath)) return defaultConfig;try {const raw = readFileSync(configPath, "utf-8");@@ -144,7 +144,7 @@ const OSS_OWNED_KEYS = new Set<keyof IxConfig>([]);export function saveConfig(config: IxConfig): void {- const configDir = join(homedir(), ".ix");+ const configDir = ixHome();const configPath = join(configDir, "config.yaml");// 0700, to match the 0600 the config itself is written with below: the file// holds credentials (Pro's instances carry a tunnel JWT and a long-lived IdPdiff --git a/ix-cli/src/cli/ix-home.ts b/ix-cli/src/cli/ix-home.tsnew file mode 100644index 00000000..46607d88--- /dev/null+++ b/ix-cli/src/cli/ix-home.ts@@ -0,0 +1,30 @@+import { homedir } from "node:os";+import { join } from "node:path";++/**+ * The directory Ix keeps its state in: `$IX_HOME` when set, else `~/.ix`.+ *+ * Single source of truth. Before this existed, `~/.ix` was spelled out in nine+ * places across three idioms -- some honouring IX_HOME, some not -- and the+ * ones that did not were `config.ts` (config.yaml, the workspace registry,+ * ingest mtimes, map baselines, stitch scopes) and `bootstrap.ts`. That is+ * nearly all of the state a run reads and writes, so a harness that set+ * IX_HOME to isolate itself still drove the developer's real config: it took+ * its endpoint from `~/.ix/config.yaml` and registered its throwaway+ * worktrees there as workspaces. A stale endpoint in that file then failed+ * every Ix-mode run of an outside benchmark while its baseline arm passed,+ * which reads like an Ix regression rather than a leaked environment.+ *+ * Resolved on every call, deliberately not cached in a module-level const.+ * A `const IX_HOME = process.env.IX_HOME || ...` binds at import time, which+ * makes isolation a module-registry problem rather than an environment one:+ * a test that sets IX_HOME in `beforeEach` is isolated when its file runs+ * alone and not when another file imported the module first. That is exactly+ * how #498 wrote a bogus `99.0.0` upgrade notice into a real `~/.ix`. Five+ * modules still bind it that way (`backend-status`, `backend-version`,+ * `docker`, `upgrade`, `view`); each derives further path constants from it,+ * so converting them is a wider change than this one and is left as follow-up.+ */+export function ixHome(): string {+ return process.env.IX_HOME || join(homedir(), ".ix");+}diff --git a/ix-cli/src/cli/single-flight.ts b/ix-cli/src/cli/single-flight.tsindex ade62fa7..88888a88 100644--- a/ix-cli/src/cli/single-flight.ts+++ b/ix-cli/src/cli/single-flight.ts@@ -1,7 +1,8 @@import { mkdirSync, writeFileSync, readFileSync, rmSync, openSync, closeSync, realpathSync } from "node:fs";import { join, resolve } from "node:path";-import { homedir, hostname } from "node:os";+import { hostname } from "node:os";import { createHash } from "node:crypto";+import { ixHome } from "./ix-home.js";// ---------------------------------------------------------------------------// CLI-level single-flight lock for `ix map` / ingest.@@ -26,7 +27,7 @@ import { createHash } from "node:crypto";// Lock directory. Overridable via IX_LOCK_DIR (used by tests, and handy if// ~/.ix is read-only). Read per call so the override can change between runs.function lockDir(): string {- return process.env.IX_LOCK_DIR || join(homedir(), ".ix", "locks");+ return process.env.IX_LOCK_DIR || join(ixHome(), "locks");}// Default: a held lock older than this is presumed stale (its holder crasheddiff --git a/ix-cli/vitest.config.ts b/ix-cli/vitest.config.tsindex b180fe32..6a13d8d7 100644--- a/ix-cli/vitest.config.ts+++ b/ix-cli/vitest.config.ts@@ -2,6 +2,8 @@ import { configDefaults, defineConfig } from "vitest/config";export default defineConfig({test: {+ // Strips an ambient IX_HOME before each file; see the comment in the file.+ setupFiles: ["./vitest.setup.ts"],// vitest 4 dropped `dist/` from its built-in exclude list. Without this the// compiled `dist/**/*.test.js` copies emitted by `npm run build` get// collected and fail (they read sibling `.ts` sources that only exist underdiff --git a/ix-cli/vitest.setup.ts b/ix-cli/vitest.setup.tsnew file mode 100644index 00000000..cb8a4b76--- /dev/null+++ b/ix-cli/vitest.setup.ts@@ -0,0 +1,15 @@+// Runs before every test file (vitest `setupFiles`).+//+// Strip an ambient IX_HOME. `config.ts` resolves the state directory through+// `ixHome()` -- `$IX_HOME`, else `~/.ix` -- so a developer, or a harness such+// as a benchmark, that has IX_HOME exported would otherwise have every test+// that isolates itself by overriding HOME write to THEIR real state directory+// instead of the temp home it set up: a HOME override relocates `~/.ix`, not+// `$IX_HOME`. Eight files isolate that way today.+//+// Deleting the variable here restores the invariant those files were written+// against, and costs nothing for the files that set IX_HOME themselves: they+// do so in `beforeEach`, which runs after this. Per file, not once per worker+// -- vitest re-runs setupFiles for each file, and `process.env` is per worker+// under the default forks pool, so no file can leak an IX_HOME to the next.+delete process.env.IX_HOME;