@sanqianx/ai-coding-event-bridge-console 0.5.1 → 0.6.0

package/src/bridge/core/normalizer.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const { randomUUID } = require('crypto');
+const { validateAndNormalizeEvent } = require('./event-schema');
+
+function assignTurnIdForPrompt() {
+  // A real captured user prompt owns a fresh turn identity. This is identity
+  // assignment for captured evidence, never content fabrication.
+  return `turn_${randomUUID()}`;
+}
+
+/**
+ * Claude Code hook payload -> normalized event.
+ * Claude Code ships the event name as hook_event_name; hookName/hook_name
+ * variants are accepted for compatibility. UserPromptSubmit carries the exact
+ * user prompt; Stop yields an assistant_response only when
+ * last_assistant_message exists — an empty Stop is not conversation evidence
+ * and produces no event. Turn closure binding happens in the journal's
+ * canonical append path.
+ */
+function hookEventName(raw) {
+  return raw.hook_event_name || raw.hookName || raw.hook_name || null;
+}
+
+function normalizeClaudeCode(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const base = { source: 'claude-code' };
+  if (hookEventName(raw) === 'UserPromptSubmit' || raw.eventType === 'user_prompt') {
+    const content = typeof raw.prompt === 'string' ? raw.prompt : null;
+    const event = {
+      ...base,
+      eventType: 'user_prompt',
+      role: 'user',
+      content,
+      sessionId: raw.session_id || null,
+      turnId: raw.turnId || assignTurnIdForPrompt(),
+      repoIdentity: raw.repoIdentity,
+      projectPath: raw.cwd,
+      identityConfidence: content === null ? 'partial' : 'exact',
+      captureStatus: content === null ? 'partial' : 'complete',
+      rawEventType: hookEventName(raw) || 'user_prompt'
+    };
+    return validateAndNormalizeEvent(event);
+  }
+  if (hookEventName(raw) === 'Stop' || raw.eventType === 'assistant_response') {
+    if (typeof raw.last_assistant_message !== 'string' || !raw.last_assistant_message) {
+      return null;
+    }
+    return validateAndNormalizeEvent({
+      ...base,
+      eventType: 'assistant_response',
+      role: 'assistant',
+      content: raw.last_assistant_message,
+      sessionId: raw.session_id || null,
+      turnId: raw.turnId || null,
+      repoIdentity: raw.repoIdentity,
+      projectPath: raw.cwd,
+      identityConfidence: 'partial',
+      captureStatus: 'complete',
+      rawEventType: hookEventName(raw) || 'assistant_response'
+    });
+  }
+  return null;
+}
+
+/**
+ * Codex events arrive via notify + session parsing (BR05 owns the parser).
+ * The normalizer only maps a parsed turn record to the standard event shape.
+ */
+function normalizeCodex(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  if (raw.eventType === 'user_prompt' || raw.eventType === 'assistant_response') {
+    return validateAndNormalizeEvent({
+      source: 'codex',
+      eventType: raw.eventType,
+      role: raw.eventType === 'user_prompt' ? 'user' : 'assistant',
+      content: typeof raw.content === 'string' ? raw.content : null,
+      sessionId: raw.sessionId || null,
+      turnId: raw.turnId || (raw.eventType === 'user_prompt' ? assignTurnIdForPrompt() : null),
+      repoIdentity: raw.repoIdentity,
+      projectPath: raw.projectPath || raw.cwd,
+      identityConfidence: raw.identityConfidence,
+      captureStatus: raw.captureStatus,
+      rawEventType: raw.rawEventType
+    });
+  }
+  return null;
+}
+
+/**
+ * OpenCode plugin events: user/assistant lifecycle from the official plugin.
+ */
+function normalizeOpenCode(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  if (raw.type === 'user' || raw.type === 'assistant') {
+    const isUser = raw.type === 'user';
+    return validateAndNormalizeEvent({
+      source: 'opencode',
+      eventType: isUser ? 'user_prompt' : 'assistant_response',
+      role: isUser ? 'user' : 'assistant',
+      content: typeof raw.text === 'string' ? raw.text : null,
+      sessionId: raw.sessionId || null,
+      turnId: isUser ? (raw.turnId || assignTurnIdForPrompt()) : raw.turnId || null,
+      repoIdentity: raw.repoIdentity,
+      projectPath: raw.cwd || raw.projectPath,
+      identityConfidence: raw.identityConfidence,
+      captureStatus: raw.captureStatus,
+      rawEventType: raw.type
+    });
+  }
+  return null;
+}
+
+module.exports = { normalizeClaudeCode, normalizeCodex, normalizeOpenCode };

package/src/bridge/core/paths.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+function bridgeHome(explicit) {
+  if (explicit) return explicit;
+  if (process.env.AI_CODING_EVENT_BRIDGE_HOME) return process.env.AI_CODING_EVENT_BRIDGE_HOME;
+  return path.join(os.homedir(), '.ai-coding-event-bridge');
+}
+
+module.exports = { bridgeHome };

package/src/bridge/core/project-registry.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { writeJsonAtomicSync, readJsonIfExists, ensureDirSync } = require('./fs-utils');
+const { CrossProcessLock } = require('./lock');
+const { resolveRepoContext, comparisonForm, repoIdentityKey } = require('./repo-context');
+
+const REGISTRY_VERSION = 1;
+
+/**
+ * Imported-project registry, persisted at `<home>/projects.json`. A registered
+ * project owns a durable journal at `<store>/journal`; capture routes events
+ * whose repoIdentity.workspaceId matches the project id there instead of the
+ * global journal. Removing a project only unregisters it — its data on disk is
+ * never touched.
+ */
+
+function registryFile(home) {
+  return path.join(home, 'projects.json');
+}
+
+function registryLockFile(home) {
+  return path.join(home, 'locks', 'projects.lock');
+}
+
+function loadRegistry(home) {
+  const raw = readJsonIfExists(registryFile(home));
+  if (!raw || !Array.isArray(raw.projects)) {
+    return { version: REGISTRY_VERSION, projects: [] };
+  }
+  return {
+    version: raw.version || REGISTRY_VERSION,
+    projects: raw.projects.filter(
+      (project) => project && typeof project === 'object' && typeof project.id === 'string' && typeof project.store === 'string'
+    )
+  };
+}
+
+function sameComparisonPath(a, b) {
+  return comparisonForm(a) === comparisonForm(b);
+}
+
+function defaultStoreFor(home, name) {
+  return path.join(home, 'projects', name);
+}
+
+async function addProject({ home, path: projectDir, store, resolveRepo = resolveRepoContext } = {}) {
+  if (typeof home !== 'string' || !home) {
+    throw new Error('addProject requires home');
+  }
+  if (typeof projectDir !== 'string' || !projectDir.trim()) {
+    const err = new Error('addProject requires a project directory');
+    err.code = 'PROJECT_PATH_REQUIRED';
+    throw err;
+  }
+  let stat = null;
+  try {
+    stat = fs.statSync(projectDir);
+  } catch (_) {
+    stat = null;
+  }
+  if (!stat || !stat.isDirectory()) {
+    const err = new Error(`project directory does not exist: ${projectDir}`);
+    err.code = 'PROJECT_DIR_INVALID';
+    throw err;
+  }
+
+  // The registry only accepts Git work trees: event identity (workspaceId) is
+  // derived from the Git toplevel, so a non-Git folder could never match the
+  // events captured inside it. Importing a subdirectory resolves to its repo
+  // root, which is the identity events actually carry.
+  const repo = await resolveRepo(projectDir);
+  if (!repo || !repo.repoIdentity) {
+    const err = new Error(`not a Git work tree (no repo identity): ${projectDir}`);
+    err.code = 'PROJECT_NOT_GIT';
+    throw err;
+  }
+
+  const name = path.basename(repo.projectPath) || repo.projectPath;
+  const entry = {
+    id: repo.repoIdentity.workspaceId,
+    name,
+    path: repo.projectPath,
+    remote: repo.repoIdentity.remote || null,
+    store: typeof store === 'string' && store.trim() ? path.resolve(store) : defaultStoreFor(home, name),
+    createdAt: new Date().toISOString()
+  };
+
+  const lock = new CrossProcessLock(registryLockFile(home));
+  return lock.withLock(async () => {
+    const registry = loadRegistry(home);
+    if (registry.projects.some((project) => project.id === entry.id)) {
+      const err = new Error(`project already imported: ${entry.path}`);
+      err.code = 'PROJECT_DUPLICATE';
+      throw err;
+    }
+    if (registry.projects.some((project) => sameComparisonPath(project.path, entry.path))) {
+      const err = new Error(`project path already imported: ${entry.path}`);
+      err.code = 'PROJECT_DUPLICATE';
+      throw err;
+    }
+    if (registry.projects.some((project) => sameComparisonPath(project.store, entry.store))) {
+      const err = new Error(`store location already used by another project: ${entry.store}`);
+      err.code = 'PROJECT_STORE_CONFLICT';
+      throw err;
+    }
+    try {
+      ensureDirSync(path.join(entry.store, 'journal'));
+    } catch (_) {
+      const err = new Error(`cannot create journal directory at: ${entry.store}`);
+      err.code = 'PROJECT_STORE_INVALID';
+      throw err;
+    }
+    writeJsonAtomicSync(registryFile(home), {
+      version: REGISTRY_VERSION,
+      projects: registry.projects.concat([entry])
+    });
+    return { ...entry };
+  });
+}
+
+async function removeProject({ home, id } = {}) {
+  if (typeof home !== 'string' || !home) {
+    throw new Error('removeProject requires home');
+  }
+  if (typeof id !== 'string' || !id) {
+    const err = new Error('removeProject requires a project id');
+    err.code = 'PROJECT_ID_REQUIRED';
+    throw err;
+  }
+  const lock = new CrossProcessLock(registryLockFile(home));
+  return lock.withLock(async () => {
+    const registry = loadRegistry(home);
+    let removed = null;
+    const projects = [];
+    for (const project of registry.projects) {
+      if (project.id === id) {
+        removed = project;
+      } else {
+        projects.push(project);
+      }
+    }
+    if (!removed) {
+      const err = new Error(`project not registered: ${id}`);
+      err.code = 'PROJECT_NOT_FOUND';
+      throw err;
+    }
+    writeJsonAtomicSync(registryFile(home), { version: REGISTRY_VERSION, projects });
+    return { ...removed };
+  });
+}
+
+function listProjects(home) {
+  return loadRegistry(home).projects.map((project) => ({ ...project }));
+}
+
+// Registry lookup by capture identity (repoIdentity.workspaceId, or the
+// identity string itself for legacy records): the same rule journal routing
+// uses to pick a project's journal.
+function findProject(home, repoIdentity) {
+  const key = repoIdentityKey(repoIdentity);
+  if (!key) return null;
+  const project = loadRegistry(home).projects.find((candidate) => candidate.id === key);
+  return project ? { ...project } : null;
+}
+
+module.exports = {
+  REGISTRY_VERSION,
+  registryFile,
+  loadRegistry,
+  addProject,
+  removeProject,
+  listProjects,
+  findProject
+};

package/src/bridge/core/repo-context.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFile } = require('child_process');
+
+const REPO_IDENTITY_SCHEMA = 'repo-identity/v1';
+
+function normalizeGitUrl(url) {
+  if (typeof url !== 'string') return null;
+  let u = url.trim();
+  if (!u) return null;
+  let match = /^git@([^:]+):(.+?)(?:\.git)?$/i.exec(u);
+  if (match) return `${match[1].toLowerCase()}/${match[2].replace(/\.git$/, '')}`;
+  match = /^(?:https?|ssh|git):\/\/(?:[^@]+@)?([^/]+)\/(.+?)(?:\.git)?$/i.exec(u);
+  if (match) return `${match[1].toLowerCase()}/${match[2].replace(/\.git$/, '')}`;
+  return u.replace(/\.git$/, '');
+}
+
+function runGitDefault(args, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, windowsHide: true }, (err, stdout) => {
+      if (err) return reject(err);
+      resolve(String(stdout).trim());
+    });
+  });
+}
+
+function realpathBestEffort(target) {
+  try {
+    return fs.realpathSync.native ? fs.realpathSync.native(target) : fs.realpathSync(target);
+  } catch (_) {
+    return null;
+  }
+}
+
+// Comparison form: identity comparisons are case-insensitive on Windows and
+// separator-insensitive everywhere. The display workspaceRoot keeps its
+// on-disk casing; only the hash/comparison form is normalized.
+function comparisonForm(target) {
+  let value = String(target).replace(/\\/g, '/');
+  while (value.length > 1 && value.endsWith('/')) value = value.slice(0, -1);
+  if (process.platform === 'win32') value = value.toLowerCase();
+  return value;
+}
+
+function workspaceIdFor(workspaceRoot) {
+  const digest = crypto.createHash('sha256').update(comparisonForm(workspaceRoot)).digest('hex');
+  return `sha256:${digest}`;
+}
+
+function isValidRepoIdentityV1(identity) {
+  return Boolean(
+    identity &&
+    typeof identity === 'object' &&
+    identity.schema === REPO_IDENTITY_SCHEMA &&
+    typeof identity.workspaceId === 'string' &&
+    /^sha256:[0-9a-f]{64}$/.test(identity.workspaceId) &&
+    typeof identity.workspaceRoot === 'string' &&
+    identity.workspaceRoot.length > 0 &&
+    (identity.commonDir === null || identity.commonDir === undefined || typeof identity.commonDir === 'string') &&
+    (identity.remote === null || identity.remote === undefined || typeof identity.remote === 'string')
+  );
+}
+
+// Journal/projection key. v1 identities key by workspaceId; plain strings are
+// legacy journal records written before repo-identity/v1 and stay readable.
+function repoIdentityKey(identity) {
+  if (identity === null || identity === undefined) return null;
+  if (typeof identity === 'string') return identity;
+  if (isValidRepoIdentityV1(identity)) return identity.workspaceId;
+  return null;
+}
+
+// Turn-namespace key: events with no repo identity at all share the 'no-repo'
+// namespace so same-session binding still works outside Git repos, while
+// malformed identity objects get a unique namespace and never cross-bind.
+function turnScopeKey(identity) {
+  if (identity === null || identity === undefined) return 'no-repo';
+  const key = repoIdentityKey(identity);
+  if (key !== null) return key;
+  try {
+    return `invalid:${JSON.stringify(identity).slice(0, 64)}`;
+  } catch (_) {
+    return 'invalid:unserializable';
+  }
+}
+
+function sameRepoIdentity(a, b) {
+  const keyA = repoIdentityKey(a);
+  const keyB = repoIdentityKey(b);
+  if (keyA === null || keyB === null) return false;
+  return keyA === keyB;
+}
+
+function buildRepoIdentityV1({ workspaceRoot, commonDir = null, remote = null }) {
+  return {
+    schema: REPO_IDENTITY_SCHEMA,
+    workspaceId: workspaceIdFor(workspaceRoot),
+    workspaceRoot,
+    commonDir: commonDir === undefined ? null : commonDir,
+    remote: remote === undefined ? null : remote
+  };
+}
+
+/**
+ * Canonical workspace identity for an authoritative development cwd.
+ *
+ * 1. `git rev-parse --show-toplevel` (authoritative Git working tree root)
+ * 2. realpath + canonical separators for the display root
+ * 3. workspaceId = sha256 over the comparison form (case-insensitive on win32)
+ * 4. commonDir from `git rev-parse --path-format=absolute --git-common-dir`
+ *    (metadata: worktrees share it, but their workspaceIds differ)
+ * 5. normalized origin URL as metadata only — never the primary identity
+ *
+ * Non-Git cwd => repoIdentity null + identityConfidence 'unavailable'.
+ * No fallback to process.cwd, no fake workspaceId, remote never overrides.
+ */
+async function resolveRepoContext(cwd, { runGit = runGitDefault } = {}) {
+  const projectPath = realpathBestEffort(cwd) || path.resolve(cwd);
+  let toplevel = null;
+  try {
+    toplevel = await runGit(['rev-parse', '--show-toplevel'], cwd);
+  } catch (_) {
+    return {
+      repoIdentity: null,
+      projectPath,
+      branch: null,
+      headAtCapture: null,
+      identityConfidence: 'unavailable'
+    };
+  }
+  const realToplevel = path.resolve(realpathBestEffort(toplevel) || toplevel);
+
+  let commonDir = null;
+  try {
+    const rawCommonDir = await runGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+    if (rawCommonDir) commonDir = path.resolve(realpathBestEffort(rawCommonDir) || rawCommonDir);
+  } catch (_) {
+    commonDir = null;
+  }
+
+  let origin = null;
+  try {
+    origin = await runGit(['config', '--get', 'remote.origin.url'], cwd);
+  } catch (_) {
+    origin = null;
+  }
+  let branch = null;
+  try {
+    branch = await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+  } catch (_) {
+    branch = null;
+  }
+  let head = null;
+  try {
+    head = await runGit(['rev-parse', 'HEAD'], cwd);
+  } catch (_) {
+    head = null;
+  }
+
+  return {
+    repoIdentity: buildRepoIdentityV1({
+      workspaceRoot: realToplevel,
+      commonDir,
+      remote: normalizeGitUrl(origin)
+    }),
+    projectPath: realToplevel,
+    branch: branch === 'HEAD' ? null : branch,
+    headAtCapture: head,
+    identityConfidence: 'exact'
+  };
+}
+
+module.exports = {
+  REPO_IDENTITY_SCHEMA,
+  normalizeGitUrl,
+  resolveRepoContext,
+  realpathBestEffort,
+  comparisonForm,
+  workspaceIdFor,
+  buildRepoIdentityV1,
+  isValidRepoIdentityV1,
+  repoIdentityKey,
+  turnScopeKey,
+  sameRepoIdentity
+};

package/src/bridge/core/runtime-home.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { bridgeHome } = require('./paths');
+const { CrossProcessLock, lockPathFor } = require('./lock');
+const { writeJsonAtomicSync, readJsonIfExists, ensureDirSync, copyDirSync } = require('./fs-utils');
+const semver = require('./semver');
+
+// The shim is intentionally version-independent: AI client configs point at this
+// stable path forever, and it delegates to whatever runtime version is active.
+// It reads the client payload from stdin, forwards it to the active runtime and
+// always exits 0 — fail-open is a product invariant.
+const SHIM_SOURCE = `#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function home() {
+  return process.env.AI_CODING_EVENT_BRIDGE_HOME || path.join(os.homedir(), '.ai-coding-event-bridge');
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    try {
+      process.stdin.setEncoding('utf8');
+      process.stdin.on('data', (chunk) => (data += chunk));
+      process.stdin.on('end', () => resolve(data));
+      process.stdin.on('error', () => resolve(data));
+    } catch (_) {
+      resolve(data);
+    }
+  });
+}
+
+(async () => {
+  try {
+    const raw = await readStdin();
+    let payload = null;
+    try {
+      payload = JSON.parse(raw);
+    } catch (_) {
+      payload = null;
+    }
+    const active = JSON.parse(fs.readFileSync(path.join(home(), 'active-runtime.json'), 'utf8'));
+    const hookPath = path.join(home(), 'runtime', String(active.version), 'hook.cjs');
+    if (fs.existsSync(hookPath)) {
+      const runtime = require(hookPath);
+      if (typeof runtime.main === 'function') {
+        await runtime.main({ payload, home: home(), argv: process.argv.slice(2), env: process.env });
+      }
+    }
+  } catch (_) {
+    // Fail open by design: a broken Bridge must never block the AI client.
+  } finally {
+    process.exit(0);
+  }
+})();
+`;
+
+// The versioned runtime entry: dispatches the client payload into the
+// self-contained bridge tree materialized next to it. The capture-disable
+// environment marker is honored before any connector is even loaded.
+const RUNTIME_HOOK_SOURCE = `#!/usr/bin/env node
+'use strict';
+async function main({ payload, home, argv, env }) {
+  const effectiveEnv = env || process.env;
+  if (effectiveEnv && effectiveEnv.AI_CODING_EVENT_BRIDGE_CAPTURE === '0') {
+    return { status: 'ignored', reason: 'capture-disabled' };
+  }
+  if (payload && typeof payload === 'object') {
+    // Claude Code ships hook_event_name (also seen as hookName/hook_name);
+    // all three identify a Claude hook payload and MUST route to the Claude
+    // connector — never fall through to Codex just because session_id exists.
+    if (payload.hookName || payload.hook_event_name || payload.hook_name) {
+      const claudeEntry = require('./bridge/connectors/claude-code/hook-entry.js');
+      return claudeEntry.mainFailOpen({ home, payload, argv, env });
+    }
+    if (payload.type === 'user' || payload.type === 'assistant') {
+      const opencodeEntry = require('./bridge/connectors/opencode/hook-entry.js');
+      return opencodeEntry.mainFailOpen({ home, payload });
+    }
+    if (payload.session_id || payload.sessionId) {
+      const codexEntry = require('./bridge/connectors/codex/hook-entry.js');
+      return codexEntry.mainFailOpen({ home, payload });
+    }
+  }
+  return { status: 'ignored' };
+}
+module.exports = { main };
+`;
+
+function materializeBridgeTree(runtimeDir) {
+  const srcRoot = path.join(__dirname, '..');
+  copyDirSync(path.join(srcRoot, 'core'), path.join(runtimeDir, 'bridge', 'core'));
+  copyDirSync(path.join(srcRoot, 'connectors'), path.join(runtimeDir, 'bridge', 'connectors'));
+}
+
+function writeTextAtomicSync(file, content) {
+  const tmp = `${file}.tmp`;
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, content);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+}
+
+async function ensureRuntimeHome({ homeDir, version } = {}) {
+  const home = bridgeHome(homeDir);
+  const requestedVersion = version || require('../../../package.json').version;
+  const lock = new CrossProcessLock(lockPathFor(home, 'install.lock'));
+  return lock.withLock(async () => {
+    ensureDirSync(path.join(home, 'bin'));
+    ensureDirSync(path.join(home, 'runtime'));
+    ensureDirSync(path.join(home, 'journal'));
+    ensureDirSync(path.join(home, 'locks'));
+
+    const shimPath = path.join(home, 'bin', 'bridge-hook.cjs');
+    writeTextAtomicSync(shimPath, SHIM_SOURCE);
+
+    const runtimeDir = path.join(home, 'runtime', requestedVersion);
+    const activeFile = path.join(home, 'active-runtime.json');
+    const active = readJsonIfExists(activeFile);
+
+    const materializeRuntime = () => {
+      ensureDirSync(runtimeDir);
+      writeTextAtomicSync(path.join(runtimeDir, 'hook.cjs'), RUNTIME_HOOK_SOURCE);
+      materializeBridgeTree(runtimeDir);
+      if (!fs.existsSync(path.join(runtimeDir, 'manifest.json'))) {
+        writeJsonAtomicSync(path.join(runtimeDir, 'manifest.json'), {
+          version: requestedVersion,
+          createdAt: new Date().toISOString()
+        });
+      }
+    };
+
+    let action;
+    if (!active || !active.version) {
+      materializeRuntime();
+      writeJsonAtomicSync(activeFile, { version: requestedVersion, activatedAt: new Date().toISOString() });
+      action = 'activated';
+    } else {
+      const cmp = semver.compare(active.version, requestedVersion);
+      if (cmp === null) {
+        materializeRuntime();
+        writeJsonAtomicSync(activeFile, { version: requestedVersion, activatedAt: new Date().toISOString() });
+        action = 'activated-unparseable-active';
+      } else if (cmp === 0) {
+        materializeRuntime();
+        action = 'noop-same-version';
+      } else if (cmp < 0) {
+        const activeMajor = semver.parse(active.version).major;
+        const requestedMajor = semver.parse(requestedVersion).major;
+        if (activeMajor !== requestedMajor) {
+          return {
+            home,
+            shimPath,
+            conflict: true,
+            activeVersion: active.version,
+            requestedVersion,
+            action: 'conflict-major-mismatch'
+          };
+        }
+        materializeRuntime();
+        writeJsonAtomicSync(activeFile, { version: requestedVersion, activatedAt: new Date().toISOString() });
+        action = 'upgraded';
+      } else {
+        action = 'kept-newer';
+      }
+    }
+
+    return {
+      home,
+      shimPath,
+      conflict: false,
+      activeVersion: readJsonIfExists(activeFile).version,
+      requestedVersion,
+      action
+    };
+  });
+}
+
+module.exports = { ensureRuntimeHome, SHIM_SOURCE };