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
// Copyright 2026 Ix Infrastructure Inc.
import { readFileSync, writeFileSync, existsSync, rmSync, chmodSync, realpathSync, mkdirSync, statSync, openSync, fstatSync, closeSync } from "node:fs";
import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
import { createHash, randomBytes } from "node:crypto";
import { execFileSync } from "node:child_process";
import { createRequire } from "node:module";
import type * as Yaml from "yaml";
import { IxClient } from "../client/api.js";
import { ixHome } from "./ix-home.js";
import { isLocalEndpoint } from "./backend-version.js";
import { renameWithRetry, withConfigLock } from "./config-lock.js";
export { ConfigLockError } from "./config-lock.js";
// `yaml` is ~70 modules, loaded the first time config.yaml is actually parsed
// or written rather than on import: every command imports this file, and
// `ix --version`, or any call made where there is no config.yaml, never needs
// it. Synchronous, because `loadConfig` is.
const requireYaml = createRequire(import.meta.url);
let yamlModule: typeof Yaml | undefined;
function yaml(): typeof Yaml {
return (yamlModule ??= requireYaml("yaml") as typeof Yaml);
}
/**
* The key of a project root's per-root state files. Canonical first: `ix
* ingest <path>` resolves its root with `canonicalWorkspacePath`, and a caller
* that spelled the same root differently -- a symlink, macOS's /tmp, a Windows
* 8.3 name like RUNNER~1 -- found no baseline under its own spelling and
* re-ingested everything, every time.
*/
function rootKey(projectRoot: string): string {
return createHash("sha256").update(canonicalWorkspacePath(projectRoot)).digest("hex").slice(0, 12);
}
/**
* Path to the per-project ingest mtime cache (the "skip unchanged files on re-map"
* pre-filter). Keyed on a hash of the project root. Single source of truth shared by
* ingest (load/save), reset, and watch (clear) — all three MUST agree on this path.
*/
export function ingestMtimeCachePath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `ingest_mtimes_${key}.json`);
}
/**
* Path to the progress of an unfinished re-ingest for a new extractor (see
* `loadRebuildProgress`). Cleared with the mtime cache, since it describes the
* same graph.
*/
export function ingestRebuildPath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `ingest_rebuild_${key}.json`);
}
/**
* Path to the orphan sweeps an earlier run could not finish (see
* `loadOrphanSweepPending`). Cleared with the mtime cache, since it describes
* the same graph.
*/
export function ingestOrphanSweepPath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `ingest_orphans_${key}.json`);
}
/**
* Path to the per-file symbol summaries an incremental map resolves against
* (see `ingest-symbols.ts`). Cleared, with its journal, with the mtime cache.
*/
export function ingestSymbolsPath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `ingest_symbols_${key}.json`);
}
/** The symbol table's journal: entries changed since the table was last written in full. */
export function ingestSymbolsJournalPath(projectRoot: string): string {
return `${ingestSymbolsPath(projectRoot)}.journal`;
}
/** Path to the architecture-map completion marker for one project root. */
export function mapBaselinePath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `map_baseline_${key}.json`);
}
/**
* Path to the last `ix verify` result for one project root (see `verify.ts`).
* Deliberately not cleared with the baselines: `ix status` labels a record
* older than the last ingest instead of losing it.
*/
export function verifyRecordPath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `verify_${key}.json`);
}
/**
* Path to the last `/v1/map` response for one project root, which a map that
* ingested nothing reuses instead of asking again (see `map-result-cache.ts`).
* Cleared with the map baseline, since both describe the same hierarchy.
*/
export function mapResultCachePath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `map_result_${key}.json`);
}
/**
* Path to the "architecture map is stale" marker for one project root: an
* `ix map` after an incremental edit left its `/v1/map` request for the next
* command that reads regions (see `map-freshness.ts`). Cleared with the map
* baseline, since it describes the same hierarchy.
*/
export function mapStalePath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `map_stale_${key}.json`);
}
/**
* Path to the outcome of the last background map refresh for one project
* root (see `map-freshness.ts`): when it ran and whether it completed, and
* why not. Read by `ix doctor` and `ix status`; cleared with the map baseline.
*/
export function mapRefreshOutcomePath(projectRoot: string): string {
const key = rootKey(projectRoot);
return join(ixHome(), `map_refresh_${key}.json`);
}
/**
* Path to the cached answer to "is this workspace stitched into a System?".
*
* Kept beside the ingest mtime cache and keyed the same way. See
* `readStitchScope` for why this is on disk rather than in memory.
*/
export function stitchScopeCachePath(workspaceId: string): string {
const key = createHash("sha256").update(workspaceId).digest("hex").slice(0, 12);
return join(ixHome(), `stitch_scope_${key}.json`);
}
/**
* The stitched system for a workspace, as last answered by the backend.
*
* `ensureReadScope` memoized this per process, which is no cache at all for a
* CLI: every `ix` invocation is a fresh process, so every aggregate read paid
* the lookup again. On a large graph that lookup is ~1.5 s — for `ix smells`,
* three times the cost of the work it precedes.
*
* Returns `undefined` when there is nothing usable on disk, which is also what
* a malformed or unreadable file returns: this is a cache, so every failure
* means "ask the backend", never "fail the command".
*
* There is deliberately no TTL. A workspace's system changes when it is mapped
* or ingested, and both of those clear this file (`clearStitchScopeCache`), so
* a timer would only add a window in which the answer is wrong for no reason.
*/
export function readStitchScope(workspaceId: string): { systemId: string | null } | undefined {
try {
const raw = JSON.parse(readFileSync(stitchScopeCachePath(workspaceId), "utf-8"));
if (raw?.workspaceId !== workspaceId) return undefined; // hash collision or hand-edit
if (raw.systemId !== null && typeof raw.systemId !== "string") return undefined;
return { systemId: raw.systemId };
} catch {
return undefined;
}
}
/** Record the backend's answer. Best-effort: a cache that cannot be written is not an error. */
export function writeStitchScope(workspaceId: string, systemId: string | null): void {
try {
const path = stitchScopeCachePath(workspaceId);
mkdirSync(ixHome(), { recursive: true });
writeFileSync(path, JSON.stringify({ workspaceId, systemId }) + "\n", "utf8");
} catch { /* non-critical */ }
}
/** Drop the cached stitch answer. Called wherever the mtime cache is cleared. */
export function clearStitchScopeCache(workspaceId: string): void {
try { rmSync(stitchScopeCachePath(workspaceId), { force: true }); } catch { /* non-critical */ }
}
/** Drop the cached `/v1/map` response, so the next map asks the backend. Best-effort. */
export function clearMapResultCache(projectRoot: string): void {
try { rmSync(mapResultCachePath(projectRoot), { force: true }); } catch { /* non-critical */ }
}
/**
* Remove the architecture-map completion marker, and the cached map response
* and the stale marker with it: whatever made the marker wrong makes the
* cached hierarchy wrong too, and a map that is no longer recorded is not
* merely deferred. Leaves the source ingest baseline alone. Best-effort.
*/
export function clearMapBaseline(projectRoot: string): void {
try { rmSync(mapBaselinePath(projectRoot), { force: true }); } catch { /* non-critical */ }
try { rmSync(mapStalePath(projectRoot), { force: true }); } catch { /* non-critical */ }
try { rmSync(mapRefreshOutcomePath(projectRoot), { force: true }); } catch { /* non-critical */ }
clearMapResultCache(projectRoot);
}
/**
* Remove all local graph baselines so the next map re-ingests every file.
*
* Reset and workspace migration invalidate both the source graph and the
* hierarchy. A failed hierarchy build clears only `clearMapBaseline` instead.
*/
export function clearIngestMtimeCache(projectRoot: string): void {
try { rmSync(ingestMtimeCachePath(projectRoot), { force: true }); } catch { /* non-critical */ }
try { rmSync(ingestRebuildPath(projectRoot), { force: true }); } catch { /* non-critical */ }
try { rmSync(ingestOrphanSweepPath(projectRoot), { force: true }); } catch { /* non-critical */ }
try { rmSync(ingestSymbolsPath(projectRoot), { force: true }); } catch { /* non-critical */ }
try { rmSync(ingestSymbolsJournalPath(projectRoot), { force: true }); } catch { /* non-critical */ }
clearMapBaseline(projectRoot);
}
export interface WorkspaceConfig {
workspace_id: string;
workspace_name: string;
root_path: string;
default: boolean;
}
export interface IxConfig {
endpoint: string;
format: string;
workspace?: string;
workspaces?: WorkspaceConfig[];
/** Credentials for the local backend. See `getLocalToken`. */
auth?: { local_token?: string };
}
/** The backend a config with no `endpoint` (or no config at all) points at. */
export const DEFAULT_ENDPOINT = "http://localhost:8090";
const defaultConfig: IxConfig = {
endpoint: DEFAULT_ENDPOINT,
format: "text",
};
/**
* config.yaml exists and does not parse. Thrown rather than answered with the
* defaults: falling back silently ran every command against the default
* endpoint with no workspaces, and the first registration then saved over the
* file. The error boundary prints the path and the parser's message.
*/
export class ConfigParseError extends Error {
constructor(readonly path: string, readonly detail: string) {
super(`${path} is not valid YAML: ${detail}`);
this.name = "ConfigParseError";
}
}
/**
* The last parse of config.yaml, keyed by the file's mtime and size. A command
* loads the config a dozen times or more, and with many workspaces each YAML
* parse costs milliseconds; the key catches a write by another process, and
* `saveConfig` drops it for this one.
*/
let configMemo: { path: string; mtimeMs: number; size: number; config: IxConfig } | undefined;
export function loadConfig(): IxConfig {
const configPath = join(ixHome(), "config.yaml");
// A copy, here and below: callers edit what they get back and save it.
// Handing out the shared default let `getOrCreateWorkspace` write its new
// workspace into it, so every later load in the process that found no
// config file -- a fresh IX_HOME, a deleted file -- inherited workspaces
// that were never in either.
// One descriptor for the stat and the read, so the memo's key always
// describes the bytes it was parsed from.
let fd: number;
try {
fd = openSync(configPath, "r");
} catch {
return { ...defaultConfig };
}
let stat: { mtimeMs: number; size: number };
let raw: string;
try {
stat = fstatSync(fd);
if (configMemo && configMemo.path === configPath && configMemo.mtimeMs === stat.mtimeMs && configMemo.size === stat.size) {
return structuredClone(configMemo.config);
}
raw = readFileSync(fd, "utf-8");
} catch {
return { ...defaultConfig };
} finally {
closeSync(fd);
}
let parsed: Partial<IxConfig> | null;
const { parse } = yaml(); // outside the try: not a parse error if it fails
try {
parsed = parse(raw) as Partial<IxConfig> | null;
} catch (err) {
throw new ConfigParseError(configPath, (err instanceof Error ? err.message : String(err)).split("\n")[0]!);
}
if (parsed === null || parsed === undefined) parsed = {}; // an empty file
if (typeof parsed !== "object" || Array.isArray(parsed)) {
throw new ConfigParseError(configPath, "the top level is not a mapping of settings");
}
// Normalize workspace_id to a string. saveConfig quotes an all-digit path-hash
// id, but a hand-edited or legacy unquoted value parses from YAML as a number,
// which then silently breaks string id comparisons (e.g. migration detection
// would re-key a workspace that is already on the correct id).
if (Array.isArray(parsed.workspaces)) {
parsed.workspaces = parsed.workspaces.map((w) => ({ ...w, workspace_id: String(w.workspace_id) }));
}
const config = { ...defaultConfig, ...parsed };
configMemo = { path: configPath, mtimeMs: stat.mtimeMs, size: stat.size, config: structuredClone(config) };
return config;
}
/**
* The `format` setting alone, for command registration, which runs before
* anything else on every invocation -- `ix --version` included. A full parse
* of a config with a thousand workspaces is ~60 ms, all of it for one scalar
* that sits on its own top-level line, so this reads that line. A memoised
* parse is used when there is one. Undefined when the file or the key is
* missing or unreadable: registration never fails on the config.
*/
export function readConfiguredFormat(): string | undefined {
const configPath = join(ixHome(), "config.yaml");
if (configMemo?.path === configPath) {
try {
const st = statSync(configPath);
if (st.mtimeMs === configMemo.mtimeMs && st.size === configMemo.size) return configMemo.config.format;
} catch { return undefined; }
}
let raw: string;
try { raw = readFileSync(configPath, "utf-8"); } catch { return undefined; }
const m = /^format:[ \t]*(?:"([^"\n]*)"|'([^'\n]*)'|([^\s#]+))[ \t]*(?:#.*)?$/m.exec(raw);
return m ? (m[1] ?? m[2] ?? m[3]) : undefined;
}
/** Test hook: forget the memoised parse. */
export function resetConfigMemo(): void {
configMemo = undefined;
}
/**
* Read config.yaml, apply `mutate`, and write it back, with no other Ix
* process writing it in between.
*
* `saveConfig` alone is atomic per write but last-writer-wins: eight `ix map`
* runs registering eight new repositories each read the file, each appended
* its own workspace, and each renamed its copy over the others' -- leaving one
* or two of the eight. Under the lock each one reads what the previous one
* wrote. A writer that cannot get the lock waits, breaks it if its holder is
* gone, and otherwise fails with `ConfigLockError`; it never writes unlocked
* (see config-lock.ts).
*
* `mutate` gets a fresh read, never the memoised one, and returns the config
* to save, or undefined to leave the file as it is. It must be synchronous.
*/
export function updateConfig<T>(mutate: (config: IxConfig) => { save?: IxConfig; result: T }): T {
const configPath = join(ixHome(), "config.yaml");
return withConfigLock(configPath, `config write ${configPath}`, () => {
configMemo = undefined;
const { save, result } = mutate(loadConfig());
if (save) saveConfig(save);
return result;
});
}
/**
* Run `fn` holding the config lock, for a write that is not a plain
* `updateConfig` -- creating the file, say. Synchronous only.
*/
export function withConfigWriteLock<T>(fn: () => T): T {
const configPath = join(ixHome(), "config.yaml");
return withConfigLock(configPath, `config write ${configPath}`, fn);
}
// Keys the OSS schema owns. For these, the in-memory `config` argument is
// the source of truth — including absence (a missing key means "delete from
// disk"). Anything outside this set is owned by extension packages (e.g.
// Pro's `active` / `instances`) or by user hand-edits, and is preserved
// untouched by OSS writes.
//
// Keep this in sync with the IxConfig interface above. New OSS fields must
// be added here, otherwise OSS code can't delete or unset them.
const OSS_OWNED_KEYS = new Set<keyof IxConfig>([
"endpoint",
"format",
"workspace",
"workspaces",
"auth",
]);
/**
* Write `config` over config.yaml, keeping the keys OSS does not own. Takes the
* config lock (re-entrantly, so `updateConfig` can call it), and re-reads the
* file under it, so the keys it preserves are the current ones.
*/
export function saveConfig(config: IxConfig): void {
const configDir = ixHome();
const configPath = join(configDir, "config.yaml");
withConfigLock(configPath, `config write ${configPath}`, () => writeConfigLocked(config, configDir, configPath));
}
function writeConfigLocked(config: IxConfig, configDir: string, configPath: string): void {
// 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
// refresh token), and a directory created at the default umask (typically
// 0755) lets anyone on the host list the names beside it. `mode` applies only
// to directories this call creates, so an existing ~/.ix keeps its own mode.
mkdirSync(configDir, { recursive: true, mode: 0o700 });
let existing: Record<string, unknown> = {};
if (existsSync(configPath)) {
const { parse } = yaml(); // outside the try: not a parse error if it fails
try {
const parsed = parse(readFileSync(configPath, "utf-8"));
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
existing = parsed as Record<string, unknown>;
}
} catch (err) {
// Refuse rather than start from `{}`: that rewrote the file with only
// this call's fields, silently dropping every other workspace, a custom
// endpoint and extension state such as Pro's credentials -- all over
// one typo in a hand edit.
throw new Error(
`${configPath} is not valid YAML, so Ix will not overwrite it. ` +
`Fix or remove the file and run the command again. (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`,
{ cause: err },
);
}
}
// Drop OSS-owned keys from the disk snapshot — the in-memory `config`
// is authoritative for those. Keep everything else (extension fields,
// user-added fields) so OSS writes never clobber them.
const preserved: Record<string, unknown> = {};
for (const [k, v] of Object.entries(existing)) {
if (!OSS_OWNED_KEYS.has(k as keyof IxConfig)) preserved[k] = v;
}
const merged: Record<string, unknown> = { ...preserved, ...(config as unknown as Record<string, unknown>) };
// Atomic write: serialize to a private (0600) temp file in the SAME directory,
// then rename it over the target. The config holds credentials (Pro's instances
// carry a tunnel JWT and a long-lived IdP refresh token), so this avoids both a
// partially-written/looser-mode window and the read-modify-write race (CodeQL
// js/file-system-race). Same-dir keeps the rename atomic; rename replaces on
// POSIX and Windows alike, and inherits the temp's 0600 mode (tightening any
// pre-existing group/world-readable config).
//
// On Windows the rename is MoveFileEx with REPLACE_EXISTING, which fails with
// EPERM/EBUSY while another process has the target open -- an unlocked
// reader, an indexer, antivirus -- so it is retried for a few seconds.
const tmpPath = `${configPath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
writeFileSync(tmpPath, yaml().stringify(merged), { mode: 0o600 });
try {
renameWithRetry(tmpPath, configPath);
} catch (err) {
try { rmSync(tmpPath, { force: true }); } catch { /* best effort */ }
throw err;
}
try {
chmodSync(configPath, 0o600); // belt-and-suspenders if umask altered the temp mode
} catch {
// chmod can fail on exotic filesystems; the temp's create-mode is the primary guard.
}
configMemo = undefined;
}
export function getEndpoint(): string {
return process.env.IX_ENDPOINT || loadConfig().endpoint;
}
/**
* The bearer token the client sends to `endpoint`, if any: IX_TOKEN, else the
* stored `auth.local_token`.
*
* Either goes only to a loopback endpoint. The token is the local backend's
* (`ix docker` runs it on this machine), so pointing IX_ENDPOINT at another
* host must not hand that host the credential. And a remote backend has its
* own auth: Ix Pro's cloud wrapper adds the org's JWT only to a request that
* carries no Authorization header, so a bearer set here would replace it.
*/
export function getLocalToken(endpoint: string = getEndpoint()): string | undefined {
if (!isLocalEndpoint(endpoint)) return undefined;
const explicit = process.env.IX_TOKEN?.trim();
if (explicit) return explicit;
return storedLocalToken();
}
/** The token in config.yaml's `auth.local_token`, if one is stored. */
export function storedLocalToken(): string | undefined {
const stored = loadConfig().auth?.local_token;
return typeof stored === "string" && stored.trim() ? stored.trim() : undefined;
}
/**
* The stored local token, saved first if there is none: `preferred` when given
* (a token the user already set by hand in ~/.ix/backend/.env), else a new one
* (32 random bytes, hex). Only `ix docker start --local-token` calls this: the
* token is opt-in until a release turns it on by default.
*/
export function ensureLocalToken(preferred?: string): string {
const existing = storedLocalToken();
if (existing) return existing;
return updateConfig((config) => {
const stored = config.auth?.local_token;
if (typeof stored === "string" && stored.trim()) return { result: stored.trim() };
const token = preferred?.trim() || randomBytes(32).toString("hex");
return { save: { ...config, auth: { ...config.auth, local_token: token } }, result: token };
});
}
/** Forget the stored local token. */
export function clearLocalToken(): void {
updateConfig((config) => {
if (!config.auth?.local_token) return { result: undefined };
const { local_token: _dropped, ...rest } = config.auth;
const next: IxConfig = { ...config };
if (Object.keys(rest).length > 0) next.auth = rest;
else delete next.auth;
return { save: next, result: undefined };
});
}
// Kept for @ix/pro, which imports it. The factory itself is the synchronous
// `createClient` in client/factory.ts; this wrapper loads it lazily because
// that module imports `getEndpoint` from this one.
export async function createClient(): Promise<IxClient> {
const factory = await import("../client/factory.js");
// Pro's client may outlive one command: no read deadline.
return factory.createClient({ longRunning: true });
}
export function loadWorkspaces(): WorkspaceConfig[] {
const config = loadConfig();
return config.workspaces ?? []; // workspace_id already normalized to string in loadConfig
}
/**
* Is `candidate` `root` itself, or somewhere underneath it?
*
* The `relative()` form is the one this file already used to pick a workspace
* for a cwd. It handles the two cases a `startsWith` prefix test gets wrong: a
* `..` traversal comes back with leading `..` segments, and on Windows a path on
* a different drive comes back absolute. Both sides are resolved first so a
* relative input cannot slip past.
*/
export function isPathInside(root: string, candidate: string): boolean {
const rel = relative(resolvePath(root), resolvePath(candidate));
return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
}
export function canonicalWorkspacePath(input: string): string {
const resolved = resolvePath(input);
try { return realpathSync.native(resolved); }
catch { return resolved; }
}
/**
* Is a path contained by one specific root after resolving symlinks on both
* sides? This is stricter than `isReadablePath`, which deliberately allows all
* registered workspace roots for cross-workspace reads.
*/
export function isPathInsideResolvedRoot(root: string, candidate: string): boolean {
const real = (p: string) => { try { return realpathSync(p); } catch { return resolvePath(p); } };
return isPathInside(root, candidate) && isPathInside(real(root), real(candidate));
}
/**
* The roots a read command may open a file from: the workspace this invocation
* resolves to, plus every workspace the user has registered with `ix init`.
*
* Registered workspaces are included because reads legitimately span them — a
* stitched system, or `ix view --all` — and every one of them is a path the user
* put in their own config. What is NOT in the list is the rest of the disk.
*/
export function readableRoots(explicitRoot?: string): string[] {
const roots = [resolveWorkspaceRoot(explicitRoot), ...loadWorkspaces().map(w => w.root_path)];
return [...new Set(roots.filter(Boolean).map(r => resolvePath(r)))];
}
/**
* May `ix read` open this file?
*
* Symlinks are resolved on both sides before comparing, so a link planted inside
* a workspace cannot be used to hand back a file outside it. Resolving both sides
* is what keeps that from backfiring: workspace roots are themselves often
* symlinks (macOS `/tmp`, a checkout reached through one), and comparing a real
* path against a symlinked root would reject perfectly ordinary reads.
* `realpathSync` is best-effort — if either side cannot be resolved, the lexical
* path stands in, which is the same answer for everything that is not a link.
*/
export function isReadablePath(candidate: string, explicitRoot?: string): boolean {
return readableRoots(explicitRoot).some(
root => isPathInsideResolvedRoot(root, candidate),
);
}
/**
* Is `dir` the root of a linked git worktree (`git worktree add`)? Its `.git`
* is a file pointing at the main repository's `.git/worktrees/<name>`, a git
* directory that holds a `commondir` file -- git's own mark of a linked
* worktree. A submodule's `.git` file points at a full git directory with no
* `commondir`, even when it lives under `.git/worktrees/<wt>/modules/` (a
* submodule checked out in a worktree), and is not one: a submodule is part
* of the repository that contains it.
*/
export function isLinkedWorktreeRoot(dir: string): boolean {
try {
// Read, not stat-then-read: a .git directory throws EISDIR here, which is
// the "not a linked worktree" answer anyway.
const gitdir = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(join(dir, ".git"), "utf-8"))?.[1];
// Relative when written with worktree.useRelativePaths (git 2.48+).
return !!gitdir && existsSync(join(resolvePath(dir, gitdir), "commondir"));
} catch {
return false;
}
}
export function selectWorkspaceForCwd(
workspaces: WorkspaceConfig[],
cwd: string,
): WorkspaceConfig | undefined {
const canonicalCwd = canonicalWorkspacePath(cwd);
const match = workspaces
.map(workspace => ({ workspace, root: canonicalWorkspacePath(workspace.root_path) }))
.filter(({ root }) => isPathInside(root, canonicalCwd))
.sort((a, b) => b.root.length - a.root.length)[0];
if (!match) return undefined;
// A linked worktree nested inside a registered repository (Claude Code puts
// them at <repo>/.claude/worktrees/<name>) is a separate checkout, usually
// on another branch. Answering for it from the enclosing repo's workspace
// read and mapped the wrong tree; it is unmapped until it is registered,
// exactly like a sibling worktree. Lexically below the match, so a few stats.
for (let dir = canonicalCwd; dir !== match.root; dir = dirname(dir)) {
if (isLinkedWorktreeRoot(dir)) return undefined;
if (dirname(dir) === dir) break;
}
return match.workspace;
}
export function findWorkspaceForCwd(cwd: string): WorkspaceConfig | undefined {
return selectWorkspaceForCwd(loadWorkspaces(), cwd);
}
export function getDefaultWorkspace(): WorkspaceConfig | undefined {
return loadWorkspaces().find(w => w.default);
}
export function getActiveWorkspaceRoot(): string | undefined {
const cwd = process.cwd();
const nearest = findWorkspaceForCwd(cwd);
if (nearest) return nearest.root_path;
const cfg = loadConfig();
if (cfg.workspace) {
const named = loadWorkspaces().find(w => w.workspace_name === cfg.workspace);
if (named) return named.root_path;
}
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 resolvePath(root, normalized);
}
export function resolveWorkspaceRoot(explicitRoot?: string, cwd = process.cwd()): string {
// 1. Explicit --root
if (explicitRoot) return explicitRoot;
// 2. Nearest initialized workspace containing cwd
const nearest = findWorkspaceForCwd(cwd);
if (nearest) return nearest.root_path;
// 3. Named workspace from `ix config set workspace <name>`
const cfg = loadConfig();
if (cfg.workspace) {
const named = loadWorkspaces().find(w => w.workspace_name === cfg.workspace);
if (named) return named.root_path;
}
// 4. Git root: the repository the caller is standing in. Ahead of the
// default workspace for the reason `resolveMapRoot` gives: `default: true`
// marks whichever repo was mapped first, so ranking it above a local
// repository made `ix text` in an unmapped checkout search an unrelated
// one. (Graph reads from such a directory refuse outright; see
// `requireReadWorkspaceId`.)
const gitRoot = gitRootFor(cwd);
if (gitRoot) return gitRoot;
// 5. Configured default workspace, for a cwd with no local context at all
const defaultWs = getDefaultWorkspace();
if (defaultWs) return defaultWs.root_path;
// 6. cwd fallback
return cwd;
}
/**
* The git top-level containing `cwd`, or undefined outside a repository.
*
* stderr is discarded: outside a repo git writes "fatal: not a git repository"
* to it, and this is a probe, not a failure the user needs to see.
*/
export function gitRootFor(cwd: string): string | undefined {
try {
// -c: never run a core.fsmonitor command the repository's config names.
const out = execFileSync("git", ["-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "rev-parse", "--show-toplevel"], {
cwd,
encoding: "utf-8",
stdio: ["ignore", "pipe", "ignore"],
}).trim();
return out || undefined;
} catch { return undefined; }
}