@memorax/memorax-code 0.1.0

package/lib/memorax-code-adapter-common/src/repo-memory/repo-memory-update-policy.mjs

@@ -0,0 +1,165 @@
+export const DEFAULT_REPO_MEMORY_UPDATE_POLICY = "adaptive";
+export const DEFAULT_REPO_MEMORY_COMMIT_THRESHOLD = 5;
+export const DEFAULT_REPO_MEMORY_COOLDOWN_HOURS = 24;
+
+export const REPO_MEMORY_UPDATE_POLICIES = Object.freeze([
+  "every-commit",
+  "commit-count",
+  "daily",
+  "pull-request",
+  "pull-request-or-daily",
+  "adaptive",
+]);
+
+export function resolveRepoMemoryUpdatePolicy(input = {}) {
+  const rawPolicy = stringOption(input.policy)?.toLowerCase();
+  const policy = REPO_MEMORY_UPDATE_POLICIES.includes(rawPolicy)
+    ? rawPolicy
+    : DEFAULT_REPO_MEMORY_UPDATE_POLICY;
+  return {
+    policy,
+    policySource: !rawPolicy ? "default" : policy === rawPolicy ? "configured" : "invalid_fallback",
+    commitThreshold: positiveInteger(input.commitThreshold, DEFAULT_REPO_MEMORY_COMMIT_THRESHOLD),
+    cooldownHours: positiveNumber(input.cooldownHours, DEFAULT_REPO_MEMORY_COOLDOWN_HOURS),
+  };
+}
+
+export function evaluateRepoMemoryUpdatePolicy(input = {}) {
+  const settings = resolveRepoMemoryUpdatePolicy(input);
+  const commitsBehind = nonNegativeInteger(input.commitsBehind);
+  const pullRequestDetected = input.pullRequestDetected === true;
+  const age = ageHours(input);
+  const baselineStatus = stringOption(input.baselineStatus) || "ancestor";
+
+  if (baselineStatus === "missing") {
+    return decision(settings, {
+      trigger: true,
+      reason: "missing_baseline",
+      ageHours: age,
+      commitsBehind,
+      pullRequestDetected,
+      baselineStatus,
+    });
+  }
+  if (baselineStatus === "not_ancestor") {
+    return decision(settings, {
+      trigger: true,
+      reason: "baseline_not_ancestor",
+      ageHours: age,
+      commitsBehind,
+      pullRequestDetected,
+      baselineStatus,
+    });
+  }
+  if (commitsBehind === 0) {
+    return decision(settings, {
+      trigger: false,
+      reason: undefined,
+      ageHours: age,
+      commitsBehind,
+      pullRequestDetected,
+      baselineStatus,
+    });
+  }
+
+  const cooldownElapsed = age === undefined || age >= settings.cooldownHours;
+  const commitThresholdReached = commitsBehind >= settings.commitThreshold;
+  let reason;
+  if (settings.policy === "every-commit") {
+    reason = "pending_commit";
+  } else if (settings.policy === "commit-count") {
+    reason = commitThresholdReached ? "commit_threshold_reached" : undefined;
+  } else if (settings.policy === "daily") {
+    reason = cooldownElapsed ? "cooldown_elapsed" : undefined;
+  } else if (settings.policy === "pull-request") {
+    reason = pullRequestDetected ? "pull_request_detected" : undefined;
+  } else if (settings.policy === "pull-request-or-daily") {
+    reason = pullRequestDetected
+      ? "pull_request_detected"
+      : cooldownElapsed
+        ? "cooldown_elapsed"
+        : undefined;
+  } else {
+    reason = commitThresholdReached
+      ? "commit_threshold_reached"
+      : cooldownElapsed
+        ? "cooldown_elapsed"
+        : undefined;
+  }
+
+  return decision(settings, {
+    trigger: reason !== undefined,
+    reason,
+    ageHours: age,
+    commitsBehind,
+    pullRequestDetected,
+    baselineStatus,
+  });
+}
+
+export function parseRepoMemoryUpdatePolicyConfig(text) {
+  const config = {};
+  let section = "";
+  for (const rawLine of String(text || "").split(/\r?\n/)) {
+    const line = rawLine.split("#", 1)[0].trim();
+    if (!line) continue;
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      section = sectionMatch[1].trim();
+      continue;
+    }
+    if (section !== "memory.repo_update") continue;
+    const field = line.match(/^([a-z_]+)\s*=\s*(.+)$/);
+    if (!field) continue;
+    const key = field[1];
+    const rawValue = field[2].trim().replace(/^['"]|['"]$/g, "");
+    if (key === "policy") config.policy = rawValue;
+    else if (key === "commit_threshold") config.commitThreshold = positiveInteger(rawValue, undefined);
+    else if (key === "cooldown_hours") config.cooldownHours = positiveNumber(rawValue, undefined);
+  }
+  return config;
+}
+
+function decision(settings, fields) {
+  return {
+    ...settings,
+    trigger: fields.trigger,
+    reason: fields.reason,
+    ageHours: fields.ageHours,
+    commitsBehind: fields.commitsBehind,
+    pullRequestDetected: fields.pullRequestDetected,
+    baselineStatus: fields.baselineStatus,
+  };
+}
+
+function ageHours(input) {
+  const nowMs = finiteNumber(input.nowMs, Date.now());
+  const lastUpdatedAtMs = finiteNumber(input.lastUpdatedAtMs, undefined);
+  if (lastUpdatedAtMs === undefined) return undefined;
+  return Math.max(0, nowMs - lastUpdatedAtMs) / (60 * 60 * 1000);
+}
+
+function positiveInteger(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function positiveNumber(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function nonNegativeInteger(value) {
+  const parsed = Number(value);
+  if (parsed === Number.POSITIVE_INFINITY) return parsed;
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+}
+
+function finiteNumber(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function stringOption(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/lib/memorax-code-adapter-common/src/repo-memory/repo-procedure-memory-context.mjs

@@ -0,0 +1,181 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJsonFile, stringOption } from "../config-utils.mjs";
+
+const MAX_CONTEXT_CHARS = 4000;
+const MAX_FILE_BYTES = 16 * 1024;
+const MAX_FILES = 20;
+const GIT_COMMAND_TIMEOUT_MS = 2000;
+const PROCEDURE_DIRECTORY_GIT_PATH = ".repo_memory/procedure-memory";
+const PROCEDURE_DIRECTORY_RELATIVE_PATH = join(".repo_memory", "procedure-memory");
+
+export function buildRepoProcedureMemoryContext(input, options) {
+  const cwd = resolveCwd(input, options);
+  if (!cwd) return undefined;
+  const repoRoot = gitRepoRoot(cwd);
+  if (!repoRoot) return undefined;
+  const result = readTrustedProcedureFiles(repoRoot, options);
+  if (result.files.length === 0) return undefined;
+  return renderContext(result.files, result.omitted);
+}
+
+function readTrustedProcedureFiles(repoRoot, options) {
+  const directory = join(repoRoot, PROCEDURE_DIRECTORY_RELATIVE_PATH);
+  if (!existsSync(directory)) return { files: [], omitted: false };
+  try {
+    const directoryStat = lstatSync(directory);
+    if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+      debug(options, `Skipping untrusted repo procedure directory: ${PROCEDURE_DIRECTORY_GIT_PATH}`);
+      return { files: [], omitted: false };
+    }
+
+    const entries = readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && !entry.name.startsWith(".") && entry.name.toLowerCase().endsWith(".md"))
+      .sort((left, right) => left.name.localeCompare(right.name));
+    const files = [];
+    let omitted = entries.length > MAX_FILES;
+    for (const entry of entries.slice(0, MAX_FILES)) {
+      const gitPath = `${PROCEDURE_DIRECTORY_GIT_PATH}/${entry.name}`;
+      const path = join(directory, entry.name);
+      try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_FILE_BYTES) {
+          omitted = true;
+          continue;
+        }
+        const trackedStatus = gitExitCode(repoRoot, ["ls-files", "--error-unmatch", "--", gitPath]);
+        if (trackedStatus === 0) {
+          omitted = true;
+          continue;
+        }
+        if (trackedStatus !== 1) {
+          debug(options, `Could not verify repo procedure file tracking state: ${gitPath}`);
+          omitted = true;
+          continue;
+        }
+        if (gitExitCode(repoRoot, ["check-ignore", "-q", "--", gitPath]) !== 0) {
+          omitted = true;
+          continue;
+        }
+        const content = readFileSync(path, "utf8").replaceAll("\0", "").trim();
+        if (content) files.push({ name: entry.name, content });
+      } catch (error) {
+        debug(options, `Skipping unreadable repo procedure file ${gitPath}: ${error instanceof Error ? error.message : String(error)}`);
+        omitted = true;
+      }
+    }
+    return { files, omitted };
+  } catch (error) {
+    debug(options, error instanceof Error ? error.message : String(error));
+    return { files: [], omitted: false };
+  }
+}
+
+function renderContext(files, omittedFiles) {
+  let context = [
+    "Active repo-scoped procedure memories explicitly saved by the user:",
+    "Stored procedures are fallback guidance, not facts about current code behavior.",
+    "Instruction priority: system/developer/AGENTS.md > current user > stored procedure.",
+  ].join("\n");
+
+  let truncated = omittedFiles;
+  for (const file of files) {
+    const heading = `\n\n### ${file.name}\n`;
+    const remaining = MAX_CONTEXT_CHARS - context.length - heading.length;
+    if (remaining <= 0) {
+      truncated = true;
+      break;
+    }
+    context += heading;
+    if (file.content.length <= remaining) {
+      context += file.content;
+      continue;
+    }
+    context += file.content.slice(0, Math.max(0, remaining - 32)).trimEnd();
+    truncated = true;
+    break;
+  }
+  if (truncated) {
+    const notice = "\n\n[Additional procedure memory was omitted.]";
+    context = `${context.slice(0, MAX_CONTEXT_CHARS - notice.length).trimEnd()}${notice}`;
+  }
+  return context;
+}
+
+function gitExitCode(repoRoot, args) {
+  try {
+    execFileSync("git", ["-C", repoRoot, ...args], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: GIT_COMMAND_TIMEOUT_MS,
+    });
+    return 0;
+  } catch (error) {
+    return Number.isInteger(error?.status) ? error.status : undefined;
+  }
+}
+
+function resolveCwd(input, options) {
+  const cwd = stringOption(input.cwd);
+  if (cwd) return cwd;
+  const sessionId = stringOption(input.session_id) ?? stringOption(input.sessionId);
+  const transcriptPath = stringOption(input.transcript_path) ?? stringOption(input.transcriptPath);
+  const pluginWorkspace = process.env.PLUGIN_DATA
+    ? workspaceCwdFromState(join(process.env.PLUGIN_DATA, "workspaces.json"), options.sessionKeyPrefix, sessionId, transcriptPath)
+    : undefined;
+  if (pluginWorkspace) return pluginWorkspace;
+  const memoraxCodeHome = process.env.MEMORAX_CODE_HOME || join(homedir(), ".memorax-code");
+  return workspaceCwdFromState(
+    join(memoraxCodeHome, "adapters", options.adapterDir, "workspaces.json"),
+    options.sessionKeyPrefix,
+    sessionId,
+    transcriptPath,
+  );
+}
+
+function workspaceCwdFromState(path, sessionKeyPrefix, sessionId, transcriptPath) {
+  const state = readJsonFile(path);
+  if (state?.unreadable) return undefined;
+  const sessions = state?.value?.sessions && typeof state.value.sessions === "object" && !Array.isArray(state.value.sessions)
+    ? state.value.sessions
+    : {};
+  for (const key of registryKeys(sessionKeyPrefix, sessionId, transcriptPath)) {
+    const record = sessions[key];
+    const cwd = stringOption(record?.cwd) ?? stringOption(record?.workspace);
+    if (cwd) return cwd;
+  }
+  return undefined;
+}
+
+function registryKeys(sessionKeyPrefix, ...values) {
+  const keys = new Set();
+  for (const value of values) {
+    const string = stringOption(value);
+    if (!string) continue;
+    keys.add(string);
+    const base = string.split(/[\\/]/).pop()?.replace(/\.[^.]+$/, "") ?? string;
+    keys.add(base);
+    if (string.startsWith(`${sessionKeyPrefix}_`)) keys.add(string.slice(sessionKeyPrefix.length + 1));
+    else keys.add(`${sessionKeyPrefix}_${string}`);
+    if (base.startsWith(`${sessionKeyPrefix}_`)) keys.add(base.slice(sessionKeyPrefix.length + 1));
+    else keys.add(`${sessionKeyPrefix}_${base}`);
+  }
+  return keys;
+}
+
+function gitRepoRoot(cwd) {
+  try {
+    return execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: GIT_COMMAND_TIMEOUT_MS,
+    }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function debug(options, message) {
+  if (process.env[options.debugEnv] === "1") console.error(message);
+}

package/lib/memorax-code-adapter-common/src/repo-memory/repo-user-profile-context.mjs

@@ -0,0 +1,251 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { readJsonFile, stringOption } from "../config-utils.mjs";
+
+const MAX_CONTEXT_CHARS = 4000;
+const MAX_PREFERENCES_BYTES = 64 * 1024;
+const GIT_COMMAND_TIMEOUT_MS = 2000;
+const PREFERENCES_GIT_PATH = ".repo_memory/user-profile/preferences.md";
+const PREFERENCES_RELATIVE_PATH = join(".repo_memory", "user-profile", "preferences.md");
+const PREFERENCES_SCHEMA = "repo_user_profile_memory.v0.1";
+const PREFERENCES_OWNER = "repo-user-profile-memory";
+const ALLOWED_TYPES = new Set(["communication", "workflow", "environment", "profile"]);
+const ALLOWED_STATUSES = new Set(["active", "superseded", "deleted"]);
+
+export function buildRepoUserProfilePreferencesContext(input, options) {
+  const cwd = resolveCwd(input, options);
+  if (!cwd) return undefined;
+  const repoRoot = gitRepoRoot(cwd);
+  if (!repoRoot) return undefined;
+  const preferences = readTrustedPreferences(repoRoot, options);
+  if (!preferences || preferences.length === 0) return undefined;
+  return renderContext(preferences);
+}
+
+function readTrustedPreferences(repoRoot, options) {
+  const path = join(repoRoot, PREFERENCES_RELATIVE_PATH);
+  if (!existsSync(path)) return undefined;
+  try {
+    for (const directory of [dirname(path), dirname(dirname(path))]) {
+      const directoryStat = lstatSync(directory);
+      if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+        debug(options, `Skipping untrusted repo user preferences directory: ${PREFERENCES_GIT_PATH}`);
+        return undefined;
+      }
+    }
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_PREFERENCES_BYTES) {
+      debug(options, `Skipping untrusted repo user preferences: ${PREFERENCES_GIT_PATH}`);
+      return undefined;
+    }
+    const trackedStatus = gitExitCode(repoRoot, ["ls-files", "--error-unmatch", "--", PREFERENCES_GIT_PATH]);
+    if (trackedStatus === 0) {
+      debug(options, `Skipping tracked repo user preferences: ${PREFERENCES_GIT_PATH}`);
+      return undefined;
+    }
+    if (trackedStatus !== 1 || gitExitCode(repoRoot, ["check-ignore", "-q", "--", PREFERENCES_GIT_PATH]) !== 0) {
+      debug(options, `Skipping unignored repo user preferences: ${PREFERENCES_GIT_PATH}`);
+      return undefined;
+    }
+    return parseActivePreferences(readFileSync(path, "utf8"));
+  } catch (error) {
+    debug(options, error instanceof Error ? error.message : String(error));
+    return undefined;
+  }
+}
+
+function parseActivePreferences(text) {
+  if (text.includes("\0")) return undefined;
+  const metadata = parseFrontmatter(text);
+  if (
+    !metadata
+    || metadata.schema !== PREFERENCES_SCHEMA
+    || metadata.scope !== "repo"
+    || metadata.owner !== PREFERENCES_OWNER
+    || metadata.trust_state !== "user_stated"
+  ) {
+    return undefined;
+  }
+  const declaredActive = nonNegativeInteger(metadata.active_count);
+  const declaredTotal = nonNegativeInteger(metadata.total_count);
+  if (declaredActive === undefined || declaredTotal === undefined) return undefined;
+
+  const matches = [...text.matchAll(/^## Preference (?<id>pref_[^\s]+)\s*$/gm)];
+  if (matches.length !== declaredTotal) return undefined;
+  const preferences = [];
+  for (let index = 0; index < matches.length; index += 1) {
+    const match = matches[index];
+    const start = match.index + match[0].length;
+    const end = matches[index + 1]?.index ?? text.length;
+    const block = text.slice(start, end);
+    const status = stripTicks(field(block, "Status")).toLowerCase();
+    const type = stripTicks(field(block, "Type"));
+    if (!ALLOWED_STATUSES.has(status) || !ALLOWED_TYPES.has(type)) return undefined;
+    if (
+      !stripTicks(field(block, "Confidence"))
+      || !stripTicks(field(block, "Created"))
+      || !stripTicks(field(block, "Updated"))
+    ) {
+      return undefined;
+    }
+    if (status !== "active") continue;
+    const description = normalizeField(field(block, "Description"));
+    if (!description) return undefined;
+    preferences.push({
+      description,
+      appliesWhen: normalizeField(field(block, "Applies when")),
+      doNotApplyWhen: normalizeField(field(block, "Do not apply when")),
+    });
+  }
+  return preferences.length === declaredActive ? preferences : undefined;
+}
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return undefined;
+  const metadata = {};
+  for (const rawLine of match[1].split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const fieldMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!fieldMatch) return undefined;
+    metadata[fieldMatch[1]] = stripYamlScalar(fieldMatch[2]);
+  }
+  return metadata;
+}
+
+function stripYamlScalar(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && trimmed[0] === trimmed.at(-1) && ["\"", "'"].includes(trimmed[0])) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function nonNegativeInteger(value) {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().replaceAll("_", "");
+  if (!/^\d+$/.test(normalized)) return undefined;
+  const parsed = Number(normalized);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function field(block, label) {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = block.match(new RegExp(`^- ${escaped}:\\s*(.*)$`, "m"));
+  return match?.[1]?.trim() ?? "";
+}
+
+function stripTicks(value) {
+  return String(value ?? "").trim().replace(/^`|`$/g, "").trim();
+}
+
+function normalizeField(value) {
+  const normalized = stripTicks(value).replace(/\s+/g, " ").trim();
+  return normalized === "-" ? "" : normalized;
+}
+
+function renderContext(preferences) {
+  let context = [
+    "Active repo-scoped user preferences explicitly saved by the user:",
+    "Stored preferences are fallback guidance, not facts about current code behavior.",
+    "Instruction priority: system/developer/AGENTS.md > current user > stored preference.",
+    "Apply each preference only when relevant and not overridden by higher-priority instructions.",
+  ].join("\n");
+  let omitted = false;
+  for (const preference of preferences) {
+    const entry = [
+      `- Description: ${preference.description}`,
+      `  Applies when: ${preference.appliesWhen || "-"}`,
+      `  Do not apply when: ${preference.doNotApplyWhen || "-"}`,
+    ].join("\n");
+    if (`${context}\n\n${entry}`.length > MAX_CONTEXT_CHARS) {
+      omitted = true;
+      break;
+    }
+    context += `\n\n${entry}`;
+  }
+  if (omitted) {
+    const notice = "\n\n[Additional user preferences were omitted.]";
+    context = `${context.slice(0, MAX_CONTEXT_CHARS - notice.length).trimEnd()}${notice}`;
+  }
+  return context;
+}
+
+function resolveCwd(input, options) {
+  const cwd = stringOption(input.cwd);
+  if (cwd) return cwd;
+  const sessionId = stringOption(input.session_id) ?? stringOption(input.sessionId);
+  const transcriptPath = stringOption(input.transcript_path) ?? stringOption(input.transcriptPath);
+  const pluginWorkspace = process.env.PLUGIN_DATA
+    ? workspaceCwdFromState(join(process.env.PLUGIN_DATA, "workspaces.json"), options.sessionKeyPrefix, sessionId, transcriptPath)
+    : undefined;
+  if (pluginWorkspace) return pluginWorkspace;
+  const memoraxCodeHome = process.env.MEMORAX_CODE_HOME || join(homedir(), ".memorax-code");
+  return workspaceCwdFromState(
+    join(memoraxCodeHome, "adapters", options.adapterDir, "workspaces.json"),
+    options.sessionKeyPrefix,
+    sessionId,
+    transcriptPath,
+  );
+}
+
+function workspaceCwdFromState(path, sessionKeyPrefix, sessionId, transcriptPath) {
+  const state = readJsonFile(path);
+  if (state?.unreadable) return undefined;
+  const sessions = state?.value?.sessions && typeof state.value.sessions === "object" && !Array.isArray(state.value.sessions)
+    ? state.value.sessions
+    : {};
+  for (const key of registryKeys(sessionKeyPrefix, sessionId, transcriptPath)) {
+    const record = sessions[key];
+    const cwd = stringOption(record?.cwd) ?? stringOption(record?.workspace);
+    if (cwd) return cwd;
+  }
+  return undefined;
+}
+
+function registryKeys(sessionKeyPrefix, ...values) {
+  const keys = new Set();
+  for (const value of values) {
+    const string = stringOption(value);
+    if (!string) continue;
+    keys.add(string);
+    const base = string.split(/[\\/]/).pop()?.replace(/\.[^.]+$/, "") ?? string;
+    keys.add(base);
+    if (string.startsWith(`${sessionKeyPrefix}_`)) keys.add(string.slice(sessionKeyPrefix.length + 1));
+    else keys.add(`${sessionKeyPrefix}_${string}`);
+    if (base.startsWith(`${sessionKeyPrefix}_`)) keys.add(base.slice(sessionKeyPrefix.length + 1));
+    else keys.add(`${sessionKeyPrefix}_${base}`);
+  }
+  return keys;
+}
+
+function gitRepoRoot(cwd) {
+  try {
+    return execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: GIT_COMMAND_TIMEOUT_MS,
+    }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function gitExitCode(repoRoot, args) {
+  try {
+    execFileSync("git", ["-C", repoRoot, ...args], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: GIT_COMMAND_TIMEOUT_MS,
+    });
+    return 0;
+  } catch (error) {
+    return Number.isInteger(error?.status) ? error.status : undefined;
+  }
+}
+
+function debug(options, message) {
+  if (process.env[options.debugEnv] === "1") console.error(message);
+}

package/lib/memorax-code-adapter-common/src/runtime-record.d.mts

@@ -0,0 +1,55 @@
+export type JsonRuntimeRecordInvalidReason =
+  | "unreadable"
+  | "malformed_json"
+  | "invalid_record";
+
+export type JsonRuntimeRecordState =
+  | Readonly<{ status: "absent" }>
+  | Readonly<{ status: "present"; value: Record<string, unknown> }>
+  | Readonly<{ status: "invalid"; reason: JsonRuntimeRecordInvalidReason }>;
+
+export type RuntimeRecordFailureState =
+  | Readonly<{ status: "absent" }>
+  | Readonly<{ status: "invalid"; reason: string }>
+  | Readonly<{ status: "unsupported"; version: number }>;
+
+export type RuntimeRecordWriteResult<T> = Readonly<{
+  path: string;
+  record: T;
+  durability: "confirmed" | "uncertain";
+  durabilityErrorCode?: string;
+}>;
+
+export type RuntimeRecordWriteRuntime = Readonly<{
+  syncDirectory?: (path: string) => void;
+}>;
+
+export type PrivateDirectoryOptions = RuntimeRecordWriteRuntime & Readonly<{
+  durableBoundary: string;
+}>;
+
+export class RuntimeRecordError extends Error {
+  constructor(options: {
+    name: string;
+    path: string;
+    state: RuntimeRecordFailureState;
+    codePrefix: string;
+    recovery?: string;
+  });
+  readonly code: string;
+  readonly recordStatus: RuntimeRecordFailureState["status"];
+  readonly recordPath: string;
+  readonly reason?: string;
+  readonly version?: number;
+}
+
+export function readJsonRuntimeRecord(path: string): JsonRuntimeRecordState;
+export function ensurePrivateDirectory(
+  path: string,
+  options: PrivateDirectoryOptions,
+): void;
+export function writePrivateJsonRecord<T>(
+  path: string,
+  value: T,
+  options: PrivateDirectoryOptions,
+): RuntimeRecordWriteResult<T>;