@memorax/memorax-code 0.1.0

package/lib/memorax-code-codex-adapter/src/config.mjs

@@ -0,0 +1,226 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { activeCodexPluginSkillsRoot } from "../../memorax-code-adapter-common/src/clients/codex-plugin-artifact.mjs";
+import {
+  DEFAULT_BACKEND_URL,
+  adapterStatePath,
+  defaultCodexHome,
+  defaultMemoraxCodeHome,
+  normalizeBackendUrl,
+} from "./adapter-paths.mjs";
+export {
+  DEFAULT_BACKEND_URL,
+  DEFAULT_TOKEN_ENV,
+  adapterSessionRegistryPath,
+  adapterStatePath,
+  adapterWorkspaceStatePath,
+  defaultCodexHome,
+  defaultMemoraxCodeHome,
+  normalizeBackendUrl,
+} from "./adapter-paths.mjs";
+import { seedExistingCodexSessionsAsNative } from "./session-registry.mjs";
+export {
+  inspectCodexHistory,
+  readCodexSessionRegistry,
+  readCodexWorkspaceStatus,
+  readMergedCodexSessions,
+  updateCodexSessionRegistry,
+} from "./session-registry.mjs";
+import { atomicWriteJson, readAdapterState, stringOption } from "./config-utils.mjs";
+export { readAdapterState } from "./config-utils.mjs";
+
+const CODEX_ADAPTER_STATE_VERSION = 1;
+const CODEX_INTEGRATION = "hooks";
+const CODEX_MEMORY_SKILL = "memorax-code";
+
+export function enableCodexAdapter(options = {}) {
+  const codexHome = options.codexHome ?? defaultCodexHome();
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const statePath = options.statePath ?? adapterStatePath(memoraxCodeHome, "codex");
+  const previousState = readAdapterState(statePath);
+  if (previousState?.unreadable) {
+    return { ok: false, action: "enable", reason: "state_unreadable", statePath };
+  }
+  if (previousState && previousState.version !== CODEX_ADAPTER_STATE_VERSION) {
+    return {
+      ok: false,
+      action: "enable",
+      reason: "state_version_unsupported",
+      statePath,
+      expectedVersion: CODEX_ADAPTER_STATE_VERSION,
+      actualVersion: previousState.version,
+    };
+  }
+
+  const nativeBaseline = seedExistingCodexSessionsAsNative({ ...options, codexHome, memoraxCodeHome, dryRun: true });
+  const codexPluginSkillsRoot = stringOption(options.codexPluginSkillsRoot);
+  const codexSkills = codexPluginSkillsSummary(codexHome, codexPluginSkillsRoot);
+  if (codexSkills.ok === false) {
+    return { ok: false, action: "enable", reason: "skill_delivery_failed", statePath, codexSkills };
+  }
+  const state = {
+    version: CODEX_ADAPTER_STATE_VERSION,
+    runtime: "codex",
+    integration: CODEX_INTEGRATION,
+    enabled: true,
+    enabledAt: previousState?.enabled === true && stringOption(previousState.enabledAt)
+      ? previousState.enabledAt
+      : new Date().toISOString(),
+    codexHome,
+    backendUrl: normalizeBackendUrl(
+      options.backendUrl
+        ?? previousState?.backendUrl
+        ?? DEFAULT_BACKEND_URL,
+    ),
+    codexSkillDelivery: "plugin",
+    ...(codexPluginSkillsRoot
+      ? { codexPluginSkillsRoot }
+      : {}),
+  };
+  atomicWriteJson(statePath, state);
+  const seededNativeSessions = nativeBaseline.ok
+    ? seedExistingCodexSessionsAsNative({ ...options, codexHome, memoraxCodeHome })
+    : { ...nativeBaseline, skipped: true };
+  return {
+    ok: true,
+    action: "enable",
+    codexHome,
+    memoraxCodeHome,
+    statePath,
+    state,
+    installed: true,
+    enabled: true,
+    integration: CODEX_INTEGRATION,
+    changed: previousState?.enabled !== true || previousState?.integration !== CODEX_INTEGRATION || codexSkills.counts?.changed > 0,
+    seededNativeSessions,
+    codexSkills,
+  };
+}
+
+export function disableCodexAdapter(options = {}) {
+  const codexHome = options.codexHome ?? defaultCodexHome();
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const statePath = options.statePath ?? adapterStatePath(memoraxCodeHome, "codex");
+  const previousState = readAdapterState(statePath);
+  if (previousState?.unreadable) {
+    return { ok: false, action: "disable", reason: "state_unreadable", statePath };
+  }
+  if (previousState && previousState.version !== CODEX_ADAPTER_STATE_VERSION) {
+    return {
+      ok: false,
+      action: "disable",
+      reason: "state_version_unsupported",
+      statePath,
+      expectedVersion: CODEX_ADAPTER_STATE_VERSION,
+      actualVersion: previousState.version,
+    };
+  }
+  const codexSkills = codexPluginSkillsSummary(
+    codexHome,
+    stringOption(options.codexPluginSkillsRoot) ?? stringOption(previousState?.codexPluginSkillsRoot),
+  );
+  const state = {
+    version: CODEX_ADAPTER_STATE_VERSION,
+    runtime: "codex",
+    integration: CODEX_INTEGRATION,
+    enabled: false,
+    disabledAt: new Date().toISOString(),
+    codexHome,
+    backendUrl: normalizeBackendUrl(
+      options.backendUrl
+        ?? previousState?.backendUrl
+        ?? DEFAULT_BACKEND_URL,
+    ),
+  };
+  atomicWriteJson(statePath, state);
+  return {
+    ok: true,
+    action: "disable",
+    codexHome,
+    memoraxCodeHome,
+    statePath,
+    state,
+    installed: false,
+    enabled: false,
+    integration: CODEX_INTEGRATION,
+    changed: previousState?.enabled === true,
+    codexSkills,
+  };
+}
+
+export function readCodexAdapterStatus(options = {}) {
+  const codexHome = options.codexHome ?? defaultCodexHome();
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const statePath = options.statePath ?? adapterStatePath(memoraxCodeHome, "codex");
+  const state = readAdapterState(statePath);
+  const enabled = state?.unreadable !== true
+    && state?.version === CODEX_ADAPTER_STATE_VERSION
+    && state?.enabled === true
+    && state?.integration === CODEX_INTEGRATION;
+  const configuredBackendUrl = stringOption(state?.backendUrl)
+    ? normalizeBackendUrl(state.backendUrl)
+    : undefined;
+  const expectedBackendUrl = stringOption(options.backendUrl)
+    ? normalizeBackendUrl(options.backendUrl)
+    : undefined;
+  return {
+    ok: true,
+    action: "status",
+    codexHome,
+    memoraxCodeHome,
+    statePath,
+    state,
+    installed: enabled,
+    enabled,
+    integration: CODEX_INTEGRATION,
+    memoryIntegration: CODEX_INTEGRATION,
+    configuredBackendUrl,
+    expectedBackendUrl,
+    backendUrlMatches: !expectedBackendUrl
+      || configuredBackendUrl === expectedBackendUrl
+      || (!configuredBackendUrl && !enabled),
+    codexSkills: codexPluginSkillsSummary(
+      codexHome,
+      stringOption(options.codexPluginSkillsRoot) ?? stringOption(state?.codexPluginSkillsRoot),
+    ),
+  };
+}
+
+function codexPluginSkillsSummary(codexHome, explicitRootPath) {
+  const cacheRoot = codexPluginCacheRoot(codexHome);
+  const rootPath = explicitRootPath ?? activeCodexPluginSkillsRoot(codexHome) ?? cacheRoot;
+  const sourcePath = join(rootPath, CODEX_MEMORY_SKILL);
+  const ready = existsSync(join(sourcePath, "SKILL.md"));
+  const skills = [{
+    name: CODEX_MEMORY_SKILL,
+    sourcePath,
+    targetPath: "",
+    sourceKind: "plugin",
+    sourceExists: ready,
+    targetExists: false,
+    targetIsSymlink: false,
+    ok: ready,
+    status: ready ? "plugin-managed" : "missing",
+  }];
+  return {
+    ok: ready,
+    status: ready ? "plugin-managed" : "missing",
+    delivery: "plugin",
+    rootPath,
+    skills,
+    counts: {
+      total: 1,
+      linked: 0,
+      missing: ready ? 0 : 1,
+      conflict: 0,
+      sourceMissing: ready ? 0 : 1,
+      failed: 0,
+      changed: 0,
+      removed: 0,
+    },
+  };
+}
+
+function codexPluginCacheRoot(codexHome) {
+  return join(codexHome, "plugins", "cache", "memorax-code", "memorax-code-codex-adapter");
+}

package/lib/memorax-code-codex-adapter/src/session-registry.mjs

@@ -0,0 +1,331 @@
+import { existsSync, lstatSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import {
+  adapterSessionRegistryPath,
+  adapterWorkspaceStatePath,
+  defaultCodexHome,
+  defaultMemoraxCodeHome,
+} from "./adapter-paths.mjs";
+import {
+  atomicWriteJson,
+  readAdapterState,
+  sha256,
+  stringOption,
+  withJsonFileLock,
+} from "./config-utils.mjs";
+
+export function readCodexWorkspaceStatus(options = {}) {
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const path = adapterWorkspaceStatePath(memoraxCodeHome, "codex");
+  const state = readAdapterState(path);
+  const latest = state?.latest && typeof state.latest === "object" ? state.latest : undefined;
+  return {
+    ok: true,
+    path,
+    captured: Boolean(latest?.cwd),
+    latest,
+    sessionCount: state?.sessions && typeof state.sessions === "object" ? Object.keys(state.sessions).length : 0,
+    state,
+  };
+}
+
+export function inspectCodexHistory(options = {}) {
+  const codexHome = options.codexHome ?? defaultCodexHome();
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const sessionsRoot = join(codexHome, "sessions");
+  const nativeSessions = collectSessionFiles(sessionsRoot, codexHome, options);
+  const historyPath = join(codexHome, "history.jsonl");
+  return {
+    ok: true,
+    action: "inspect-history",
+    codexHome,
+    memoraxCodeHome,
+    readOnly: true,
+    native: {
+      sessionsRoot,
+      sessionsRootExists: existsSync(sessionsRoot),
+      historyPath,
+      historyExists: existsSync(historyPath),
+      sessionCount: nativeSessions.length,
+      sessions: nativeSessions,
+    },
+    memoraxCode: {
+      registryPath: adapterSessionRegistryPath(memoraxCodeHome, "codex"),
+      workspaceStatePath: adapterWorkspaceStatePath(memoraxCodeHome, "codex"),
+      registryExists: existsSync(adapterSessionRegistryPath(memoraxCodeHome, "codex")),
+      workspaceStateExists: existsSync(adapterWorkspaceStatePath(memoraxCodeHome, "codex")),
+    },
+  };
+}
+
+export function readCodexSessionRegistry(options = {}) {
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const path = options.registryPath ?? adapterSessionRegistryPath(memoraxCodeHome, "codex");
+  const state = readAdapterState(path);
+  const rawSessions = state?.sessions && typeof state.sessions === "object" && !Array.isArray(state.sessions)
+    ? state.sessions
+    : {};
+  const sessions = {};
+  for (const [key, value] of Object.entries(rawSessions)) {
+    if (!value || typeof value !== "object") continue;
+    const session = normalizeRegistrySession(key, value);
+    if (session) sessions[key] = session;
+  }
+  return {
+    ok: true,
+    action: "session-registry",
+    path,
+    exists: existsSync(path),
+    unreadable: Boolean(state?.unreadable),
+    state: {
+      version: 1,
+      runtime: "codex",
+      updatedAt: typeof state?.updatedAt === "string" ? state.updatedAt : undefined,
+      sessions,
+    },
+  };
+}
+
+export function updateCodexSessionRegistry(options = {}) {
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const path = options.registryPath ?? adapterSessionRegistryPath(memoraxCodeHome, "codex");
+  const sessionId = stringOption(options.sessionId);
+  if (!sessionId) return { ok: false, action: "mark-session", reason: "missing_session_id", message: "--session-id is required", path };
+  return withJsonFileLock(path, () => {
+    const registry = readCodexSessionRegistry({ ...options, memoraxCodeHome, registryPath: path });
+    if (registry.unreadable) {
+      return { ok: false, action: "mark-session", reason: "unreadable_registry", message: "session registry is unreadable; inspect it before overwriting", path };
+    }
+    const existing = registry.state.sessions[sessionId];
+    const now = new Date().toISOString();
+    const session = {
+      ...(existing ?? {}),
+      key: sessionId,
+      title: stringOption(options.title) ?? existing?.title,
+      codexSessionId: stringOption(options.codexSessionId) ?? existing?.codexSessionId ?? sessionId,
+      transcriptPath: stringOption(options.transcriptPath) ?? existing?.transcriptPath,
+      workspace: stringOption(options.workspace) ?? existing?.workspace,
+    };
+    const state = {
+      version: 1,
+      runtime: "codex",
+      updatedAt: now,
+      sessions: {
+        ...registry.state.sessions,
+        [sessionId]: session,
+      },
+    };
+    atomicWriteJson(path, state);
+    return { ok: true, action: "mark-session", path, session, changed: JSON.stringify(existing) !== JSON.stringify(session) };
+  });
+}
+
+export function seedExistingCodexSessionsAsNative(options = {}) {
+  const codexHome = options.codexHome ?? defaultCodexHome();
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const path = options.registryPath ?? adapterSessionRegistryPath(memoraxCodeHome, "codex");
+  const initialRegistry = readCodexSessionRegistry({ ...options, memoraxCodeHome, registryPath: path });
+  if (initialRegistry.unreadable) return unreadableCodexRegistry(path);
+  const history = inspectCodexHistory({ ...options, codexHome, memoraxCodeHome });
+  if (options.dryRun) return seedCodexSessions(path, codexHome, initialRegistry, history, false);
+  return withJsonFileLock(path, () => {
+    const registry = readCodexSessionRegistry({ ...options, memoraxCodeHome, registryPath: path });
+    if (registry.unreadable) return unreadableCodexRegistry(path);
+    return seedCodexSessions(path, codexHome, registry, history, true);
+  });
+}
+
+function seedCodexSessions(path, codexHome, registry, history, write) {
+  const existingSessions = registry.state.sessions;
+  const sessions = { ...existingSessions };
+  const now = new Date().toISOString();
+  let seeded = 0;
+  for (const item of history.native.sessions) {
+    if (findExistingRegistrySessionKey(sessions, item)) continue;
+    const transcriptPath = join(codexHome, item.relativePath);
+    sessions[item.id] = {
+      key: item.id,
+      codexSessionId: item.id,
+      transcriptPath,
+    };
+    seeded += 1;
+  }
+  if (write && seeded > 0) {
+    atomicWriteJson(path, {
+      version: 1,
+      runtime: "codex",
+      updatedAt: now,
+      sessions,
+    });
+  }
+  return { ok: true, action: "seed-native-sessions", path, inspected: history.native.sessionCount, seeded };
+}
+
+function unreadableCodexRegistry(path) {
+  return {
+    ok: false,
+    action: "seed-native-sessions",
+    reason: "unreadable_registry",
+    message: "session registry is unreadable; inspect it before seeding native Codex sessions",
+    path,
+  };
+}
+
+export function readMergedCodexSessions(options = {}) {
+  const history = inspectCodexHistory(options);
+  const registry = readCodexSessionRegistry(options);
+  const workspaceStatus = readCodexWorkspaceStatus(options);
+  if (registry.unreadable) {
+    return {
+      ok: false,
+      action: "sessions",
+      reason: "unreadable_registry",
+      message: "session registry is unreadable; sessions are not merged to avoid hiding or rewriting adapter state",
+      codexHome: history.codexHome,
+      memoraxCodeHome: history.memoraxCodeHome,
+      registryPath: registry.path,
+      nativeSessionCount: history.native.sessionCount,
+      sessionCount: 0,
+      sessions: [],
+    };
+  }
+  const workspaceByKey = workspaceRecordMap(workspaceStatus.state);
+  const registeredByCodexId = new Map();
+  for (const session of Object.values(registry.state.sessions)) {
+    if (session.codexSessionId) registeredByCodexId.set(session.codexSessionId, session);
+  }
+  const native = history.native.sessions.map((item) => {
+    const registered = registeredByCodexId.get(item.id);
+    const workspace = findWorkspaceRecord(workspaceByKey, registered?.key, item.id, registered?.transcriptPath, item.relativePath);
+    return {
+      key: registered?.key ?? item.id,
+      title: registered?.title,
+      codexSessionId: item.id,
+      relativePath: item.relativePath,
+      pathHash: item.pathHash,
+      sizeBytes: item.sizeBytes,
+      modifiedAt: item.modifiedAt,
+      workspace: registered?.workspace ?? workspace?.cwd,
+      transcriptPath: registered?.transcriptPath ?? workspace?.transcriptPath,
+      observedAt: workspace?.capturedAt,
+    };
+  });
+  const sessions = native.sort((a, b) => String(b.modifiedAt ?? "").localeCompare(String(a.modifiedAt ?? "")));
+  return {
+    ok: true,
+    action: "sessions",
+    codexHome: history.codexHome,
+    memoraxCodeHome: history.memoraxCodeHome,
+    registryPath: registry.path,
+    sessionCount: sessions.length,
+    sessions,
+  };
+}
+
+function collectSessionFiles(root, codexHome, options = {}) {
+  const requestedMaxFiles = Number(options.maxFiles);
+  const requestedMaxDepth = Number(options.maxDepth);
+  const maxFiles = Number.isFinite(requestedMaxFiles) ? Math.max(0, Math.floor(requestedMaxFiles)) : 500;
+  const maxDepth = Number.isFinite(requestedMaxDepth) ? Math.max(0, Math.floor(requestedMaxDepth)) : 8;
+  const files = [];
+  walkSessionFiles(root, 0, maxDepth, files, maxFiles);
+  return files.map((path) => sessionFileSummary(path, codexHome)).filter(Boolean);
+}
+
+function walkSessionFiles(path, depth, maxDepth, files, maxFiles) {
+  if (files.length >= maxFiles || depth > maxDepth || !existsSync(path)) return;
+  let stat;
+  try {
+    stat = lstatSync(path);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink()) return;
+  if (stat.isFile()) {
+    if (/\.(jsonl|json)$/i.test(path)) files.push(path);
+    return;
+  }
+  if (!stat.isDirectory()) return;
+  let entries = [];
+  try {
+    entries = readdirSync(path, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  entries
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .forEach((entry) => walkSessionFiles(join(path, entry.name), depth + 1, maxDepth, files, maxFiles));
+}
+
+function sessionFileSummary(path, codexHome) {
+  try {
+    const stat = statSync(path);
+    const relativePath = relative(codexHome, path);
+    const id = basename(path).replace(/\.(jsonl|json)$/i, "");
+    return {
+      id,
+      kind: "codex-session-file",
+      relativePath,
+      pathHash: sha256(relativePath).slice(0, 16),
+      sizeBytes: stat.size,
+      modifiedAt: stat.mtime.toISOString(),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeRegistrySession(key, value) {
+  return {
+    key,
+    title: stringOption(value.title),
+    codexSessionId: stringOption(value.codexSessionId),
+    transcriptPath: stringOption(value.transcriptPath),
+    workspace: stringOption(value.workspace),
+  };
+}
+
+function workspaceRecordMap(state) {
+  const raw = state?.sessions && typeof state.sessions === "object" && !Array.isArray(state.sessions)
+    ? state.sessions
+    : {};
+  const records = new Map();
+  for (const [key, value] of Object.entries(raw)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    records.set(key, value);
+  }
+  return records;
+}
+
+function findWorkspaceRecord(records, ...keys) {
+  for (const key of workspaceLookupKeys(keys)) {
+    const record = records.get(key);
+    if (record) return record;
+  }
+  return undefined;
+}
+
+function workspaceLookupKeys(keys) {
+  const result = new Set();
+  for (const key of keys) {
+    const value = stringOption(key);
+    if (!value) continue;
+    result.add(value);
+    const base = basename(value).replace(/\.[^.]+$/, "");
+    result.add(base);
+    if (value.startsWith("codex_")) result.add(value.slice("codex_".length));
+    else result.add(`codex_${value}`);
+    if (base.startsWith("codex_")) result.add(base.slice("codex_".length));
+    else result.add(`codex_${base}`);
+  }
+  return result;
+}
+
+function findExistingRegistrySessionKey(sessions, item) {
+  for (const [key, session] of Object.entries(sessions ?? {})) {
+    if (key === item.id) return key;
+    if (session?.codexSessionId === item.id) return key;
+    if (session?.transcriptPath && item.relativePath && String(session.transcriptPath).endsWith(item.relativePath)) return key;
+  }
+  return undefined;
+}

package/lib/memorax-code-codex-adapter/src/workspace-kind.mjs

@@ -0,0 +1,68 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+
+const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const nativePath = process.platform === "win32" ? win32 : posix;
+
+export function resolveCodexWorkspaceKind(input, options = {}) {
+  const explicitKind = stringValue(input?.workspace_kind) ?? stringValue(input?.workspaceKind);
+  if (explicitKind) return explicitKind;
+  return isCodexManagedTaskWorkspace(stringValue(input?.cwd), options) ? "projectless" : undefined;
+}
+
+export function isCodexManagedTaskWorkspace(value, options = {}) {
+  const path = options.path ?? nativePath;
+  if (!value || !path.isAbsolute(value)) return false;
+  const canonicalize = options.canonicalize ?? canonicalPath;
+  const workspace = canonicalize(value);
+  if (!workspace) return false;
+  const roots = options.managedRoots ?? defaultManagedRoots(options.env);
+  return roots.some((root) => managedRelativePath(canonicalize(root), workspace, path));
+}
+
+function managedRelativePath(root, workspace, pathApi) {
+  if (!root || !workspace) return false;
+  const path = pathApi.relative(root, workspace);
+  if (!path || path.startsWith(`..${pathApi.sep}`) || path === ".." || pathApi.isAbsolute(path)) return false;
+  const parts = path.split(pathApi.sep);
+  return parts.length === 2 && validIsoDate(parts[0]) && Boolean(parts[1]);
+}
+
+function defaultManagedRoots(env = process.env) {
+  const home = stringValue(process.platform === "win32" ? env.USERPROFILE : env.HOME)
+    ?? stringValue(env.HOME)
+    ?? homedir();
+  const roots = [nativePath.join(home, "Documents", "Codex")];
+  if (process.platform === "win32") {
+    for (const key of ["OneDrive", "OneDriveCommercial", "OneDriveConsumer"]) {
+      const oneDrive = stringValue(env[key]);
+      if (oneDrive) roots.push(nativePath.join(oneDrive, "Documents", "Codex"));
+    }
+  }
+  return [...new Set(roots)];
+}
+
+function canonicalPath(value) {
+  try {
+    return realpathSync(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function validIsoDate(value) {
+  const match = ISO_DATE_PATTERN.exec(value);
+  if (!match) return false;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/lib/node-version.mjs

@@ -0,0 +1,11 @@
+export const MINIMUM_NODE_MAJOR = 24;
+
+export function unsupportedNodeVersionMessage(version = process.versions.node) {
+  const value = String(version ?? "").trim();
+  const match = /^v?(\d+)(?:\.|$)/.exec(value);
+  const major = match ? Number.parseInt(match[1], 10) : undefined;
+  if (major !== undefined && major >= MINIMUM_NODE_MAJOR) return undefined;
+  const current = value || "unknown";
+  return `MemoraX Code requires Node.js ${MINIMUM_NODE_MAJOR} or newer; `
+    + `the current runtime is Node.js ${current}. Upgrade Node.js and try again.`;
+}

package/lib/npm-invocation.mjs

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export function resolveNpmInvocation(npmArgs, options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const nodePath = options.nodePath ?? process.execPath;
+  const fileExists = options.existsSync ?? existsSync;
+  if (platform !== "win32") return { command: "npm", args: npmArgs };
+  const pathApi = path.win32;
+  const candidates = [
+    env.MEMORAX_CODE_NPM_EXEC_PATH,
+    env.npm_execpath,
+    env.NPM_CLI_JS,
+    pathApi.join(pathApi.dirname(nodePath), "node_modules", "npm", "bin", "npm-cli.js"),
+    pathApi.join(
+      pathApi.dirname(pathApi.dirname(nodePath)),
+      "lib",
+      "node_modules",
+      "npm",
+      "bin",
+      "npm-cli.js",
+    ),
+  ].filter((candidate) => typeof candidate === "string" && /\.(?:cjs|js|mjs)$/i.test(candidate));
+  const npmCli = candidates.find((candidate) => fileExists(candidate));
+  if (npmCli) return { command: nodePath, args: [npmCli, ...npmArgs] };
+  throw new Error(
+    "npm CLI JavaScript entrypoint was not found; set MEMORAX_CODE_NPM_EXEC_PATH, "
+    + "npm_execpath, or NPM_CLI_JS before running memorax-code update",
+  );
+}