Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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.md
index 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 hangs
diff --git a/docs/prerequisites.md b/docs/prerequisites.md
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 call
diff --git a/ix-cli/src/cli/config.ts b/ix-cli/src/cli/config.ts
index 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 | null
export 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 IdP
diff --git a/ix-cli/src/cli/ix-home.ts b/ix-cli/src/cli/ix-home.ts
new file mode 100644
index 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.ts
index 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 crashed
diff --git a/ix-cli/vitest.config.ts b/ix-cli/vitest.config.ts
index 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 under
diff --git a/ix-cli/vitest.setup.ts b/ix-cli/vitest.setup.ts
new file mode 100644
index 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;