@memorax/memorax-code 0.1.8 → 0.1.10

package/lib/memorax-code-codebuddy-adapter/skills/memorax-code/scripts/validate_memory.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Validate authored repo-memory bundles."""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+BASELINE_FILES = [
+    Path("PROFILE.md"),
+    Path("resources/commits.md"),
+    Path("resources/prs.md"),
+    Path("resources/issues.md"),
+    Path("raw/git-commits.json"),
+]
+
+PROVIDER_RAW_FILES = [Path("raw/github-facets.json"), Path("raw/gitlab-facets.json")]
+PROVIDER_RESOURCE_FILES = [Path("resources/prs.md"), Path("resources/issues.md")]
+DISABLED_RESOURCE_SOURCES = {"history_disabled", "provider_skipped_local_only", "provider_unavailable", "github_resource_facets_unavailable", "gitlab_resource_facets_unavailable", "provider_unavailable_local_only"}
+USER_PROFILE_SIDECAR = Path("user-profile/preferences.md")
+PROCEDURE_SIDECAR_DIRECTORY = "procedure-memory"
+PLACEHOLDER_RE = re.compile(r"\[([^\]\n]+)\]")
+LINK_TARGET_AFTER_BRACKET_RE = re.compile(r"[ \t\r\n]*\(")
+
+
+def relative(path: Path, memory: Path) -> str:
+    return path.relative_to(memory).as_posix()
+
+
+def resolve_memory_root(path: Path) -> Path:
+    candidate = path.expanduser().resolve()
+    if candidate.name == ".repo_memory":
+        return candidate
+    return candidate / ".repo_memory"
+
+
+def parse_frontmatter(text: str) -> dict[str, Any]:
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+    values: dict[str, Any] = {}
+    for line in text[4:end].splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            continue
+        if (value.startswith('"') and value.endswith('"')) or (value.startswith("'") and value.endswith("'")):
+            values[key] = value[1:-1]
+        elif re.fullmatch(r"-?\d+", value):
+            values[key] = int(value)
+        elif value.lower() == "true":
+            values[key] = True
+        elif value.lower() == "false":
+            values[key] = False
+        else:
+            values[key] = value
+    return values
+
+
+def body_after_frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return text
+    end = text.find("\n---", 4)
+    if end == -1:
+        return text
+    return text[end + 4 :].lstrip("\n")
+
+
+def item_section_count(text: str) -> int:
+    body = body_after_frontmatter(text)
+    lines = body.splitlines()
+    title_seen = False
+    count = 0
+    for line in lines:
+        if line.startswith("# ") and not title_seen:
+            title_seen = True
+            continue
+        if title_seen and line.startswith("## "):
+            count += 1
+    return count
+
+
+def placeholder_matches(text: str) -> list[str]:
+    text = strip_markdown_code(text)
+    matches: list[str] = []
+    for match in PLACEHOLDER_RE.finditer(text):
+        if LINK_TARGET_AFTER_BRACKET_RE.match(text, match.end()):
+            continue
+        value = match.group(1).strip()
+        if not value or value.startswith("#"):
+            continue
+        if re.search(r"[A-Za-z]", value):
+            matches.append(f"[{value}]")
+    return matches
+
+
+def strip_markdown_code(text: str) -> str:
+    without_fences = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
+    return re.sub(r"`[^`\n]*`", "", without_fences)
+
+
+def check_exists(memory: Path, rel_path: Path, errors: list[str], checked: list[str]) -> bool:
+    path = memory / rel_path
+    checked.append(rel_path.as_posix())
+    if not path.exists():
+        errors.append(f"{rel_path.as_posix()}: required file is missing")
+        return False
+    if not path.is_file():
+        errors.append(f"{rel_path.as_posix()}: expected a file")
+        return False
+    return True
+
+
+def validate_json(path: Path, memory: Path, errors: list[str], checked: list[str]) -> None:
+    checked.append(relative(path, memory))
+    try:
+        json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        errors.append(f"{relative(path, memory)}: invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}")
+    except OSError as exc:
+        errors.append(f"{relative(path, memory)}: could not read JSON: {exc}")
+
+
+def raw_source_points_to_provider(raw_source: Any) -> bool:
+    return isinstance(raw_source, str) and raw_source.endswith(("github-facets.json", "gitlab-facets.json"))
+
+
+def validate_markdown(path: Path, memory: Path, errors: list[str], warnings: list[str], checked: list[str]) -> None:
+    checked.append(relative(path, memory))
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        errors.append(f"{relative(path, memory)}: could not read Markdown: {exc}")
+        return
+
+    frontmatter = parse_frontmatter(text)
+    rel = relative(path, memory)
+    if not frontmatter.get("schema"):
+        errors.append(f"{rel}: frontmatter field 'schema' is missing")
+
+    placeholders = placeholder_matches(text)
+    if placeholders:
+        errors.append(f"{rel}: unresolved bracket placeholder(s): {', '.join(placeholders)}")
+
+    if path.parent.name != "resources":
+        return
+
+    for field in ["source", "resource_count", "trust_state", "raw_source"]:
+        if field not in frontmatter:
+            errors.append(f"{rel}: frontmatter field '{field}' is missing")
+
+    expected = frontmatter.get("resource_count")
+    actual = item_section_count(text)
+    if isinstance(expected, int):
+        if expected != actual:
+            errors.append(f"{rel}: resource_count is {expected}, but found {actual} item section(s)")
+    elif expected is not None:
+        errors.append(f"{rel}: resource_count must be an integer")
+
+    source = frontmatter.get("source")
+    raw_source = frontmatter.get("raw_source")
+    if "source" in frontmatter and not source:
+        errors.append(f"{rel}: frontmatter field 'source' must not be empty")
+    if "trust_state" in frontmatter and not frontmatter.get("trust_state"):
+        errors.append(f"{rel}: frontmatter field 'trust_state' must not be empty")
+    if source in DISABLED_RESOURCE_SOURCES and isinstance(expected, int) and expected != 0:
+        errors.append(f"{rel}: disabled or unavailable resource source {source!r} must use resource_count 0")
+    if source in DISABLED_RESOURCE_SOURCES and raw_source:
+        errors.append(f"{rel}: disabled or unavailable resource source {source!r} must use an empty raw_source")
+    if path.name in {"commits.md", "prs.md", "issues.md"} and source not in DISABLED_RESOURCE_SOURCES and raw_source == "":
+        errors.append(f"{rel}: empty raw_source requires a disabled or unavailable source")
+    if path.name in {"prs.md", "issues.md"} and raw_source_points_to_provider(raw_source):
+        provider_path = (path.parent / raw_source).resolve()
+        if not provider_path.exists():
+            errors.append(f"{rel}: provider raw evidence is missing for raw_source {raw_source!r}")
+
+
+def provider_raw_paths(memory: Path) -> list[Path]:
+    return [memory / rel for rel in PROVIDER_RAW_FILES if (memory / rel).exists()]
+
+
+def validate(memory: Path) -> dict[str, Any]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    checked: list[str] = []
+
+    if not memory.exists():
+        errors.append(f"{memory}: .repo_memory directory is missing")
+        return {"ok": False, "errors": errors, "warnings": warnings, "checked": checked}
+    if not memory.is_dir():
+        errors.append(f"{memory}: expected .repo_memory to be a directory")
+        return {"ok": False, "errors": errors, "warnings": warnings, "checked": checked}
+
+    for rel_path in BASELINE_FILES:
+        check_exists(memory, rel_path, errors, checked)
+
+    markdown_paths = sorted(
+        path
+        for path in memory.rglob("*.md")
+        if path.is_file()
+        and path.relative_to(memory) != USER_PROFILE_SIDECAR
+        and path.relative_to(memory).parts[0] != PROCEDURE_SIDECAR_DIRECTORY
+    )
+    for path in markdown_paths:
+        if path.exists() and path.is_file():
+            validate_markdown(path, memory, errors, warnings, checked)
+
+    json_paths = sorted(path for path in (memory / "raw").rglob("*.json") if path.is_file())
+    provider_raw = provider_raw_paths(memory)
+
+    if provider_raw:
+        for rel_path in PROVIDER_RESOURCE_FILES:
+            check_exists(memory, rel_path, errors, checked)
+
+    seen_json: set[Path] = set()
+    for path in json_paths:
+        if path.exists() and path.is_file() and path not in seen_json:
+            seen_json.add(path)
+            validate_json(path, memory, errors, checked)
+
+    checked = sorted(dict.fromkeys(checked))
+    return {"ok": not errors, "errors": errors, "warnings": warnings, "checked": checked}
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate a repo-memory bundle.")
+    parser.add_argument("path", help="Path to a repository or its .repo_memory directory")
+    parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON output")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+    report = validate(resolve_memory_root(Path(args.path)))
+    print(json.dumps(report, ensure_ascii=False, indent=2 if args.pretty else None))
+    return 0 if report["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/lib/memorax-code-codebuddy-adapter/src/cli.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import {
+  defaultCodeBuddyHome,
+  disableCodeBuddyAdapter,
+  enableCodeBuddyAdapter,
+  readCodeBuddyAdapterStatus,
+  removeCodeBuddyPluginInstallation,
+} from "./config.mjs";
+
+try {
+  const parsed = parseCli(process.argv);
+  if (parsed.help) {
+    console.log("Usage: memorax-code-codebuddy [status|enable|disable|remove] [--codebuddy-home DIR] [--json]");
+    process.exit(0);
+  }
+  const options = { codeBuddyHome: parsed.home };
+  const result = parsed.command === "status"
+    ? await readCodeBuddyAdapterStatus(options)
+    : parsed.command === "enable"
+      ? await enableCodeBuddyAdapter(options)
+      : parsed.command === "disable"
+        ? await disableCodeBuddyAdapter(options)
+        : parsed.command === "remove"
+          ? await removeCodeBuddyPluginInstallation(options)
+          : undefined;
+  if (!result) throw new Error(`unknown command: ${parsed.command}`);
+  if (parsed.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(`${result.action}: ${result.ok ? "ok" : "failed"}\nhome: ${result.codeBuddyHome ?? parsed.home}`);
+  const ready = result.ok === true
+    && result.installed === true
+    && result.enabled === true
+    && result.marketplaceReady === true
+    && result.codebuddyHooks?.ok === true
+    && result.codebuddySkills?.ok === true;
+  process.exit(parsed.command === "status" ? (ready ? 0 : 1) : (result.ok ? 0 : 1));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseCli(argv) {
+  const args = argv.slice(2);
+  const command = args[0] && !args[0].startsWith("-") ? args.shift() : "status";
+  let home;
+  let json = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help") return { command, help: true };
+    if (arg === "--json") { json = true; continue; }
+    if (arg === "--codebuddy-home") {
+      home = args[++index];
+      if (!home || home.startsWith("--")) throw new Error("--codebuddy-home requires a value");
+      continue;
+    }
+    throw new Error(`unknown option: ${arg}`);
+  }
+  return { command, home: home ?? defaultCodeBuddyHome(), json, help: false };
+}

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

@@ -0,0 +1,277 @@
+import { readFileSync } from "node:fs";
+import { chmod, cp, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, relative, sep, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveHookCodeBuddyCommand } from "../../memorax-code-adapter-common/src/clients/codebuddy-command.mjs";
+import {
+  codeBuddyHookManifestConfigured,
+  materializeCodeBuddyHookManifest,
+} from "./hook-manifest.mjs";
+import {
+  codeBuddyRuntimeObservationPath,
+  readCodeBuddyRuntimeObservation,
+} from "./runtime-observation.mjs";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const VERSION = readPluginVersion();
+const PLUGIN_NAME = "memorax-code-codebuddy-adapter";
+const MARKETPLACE_NAME = "memorax-code-local";
+const PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+
+export function defaultCodeBuddyHome(env = process.env, homeDir = homedir(), platform = process.platform) {
+  return env.CODEBUDDY_HOME?.trim()
+    || env.WORKBUDDY_HOME?.trim()
+    || (platform === "win32" ? win32.join(homeDir, ".codebuddy") : join(homeDir, ".workbuddy"));
+}
+// CodeBuddy stores installed plugin caches under the marketplace namespace.
+export function codeBuddyInstallPath(home = defaultCodeBuddyHome()) { return join(home, "plugins", "cache", MARKETPLACE_NAME, PLUGIN_NAME, VERSION); }
+export function installedRegistryPath(home = defaultCodeBuddyHome()) { return join(home, "plugins", "installed_plugins.json"); }
+export function codeBuddySettingsPath(home = defaultCodeBuddyHome()) { return join(home, "settings.json"); }
+export function knownMarketplacesPath(home = defaultCodeBuddyHome()) { return join(home, "plugins", "known_marketplaces.json"); }
+export function marketplaceRoot(home = defaultCodeBuddyHome()) { return join(home, "plugins", "marketplaces", MARKETPLACE_NAME); }
+export function marketplacePluginPath(home = defaultCodeBuddyHome()) { return join(marketplaceRoot(home), "plugins", PLUGIN_NAME); }
+
+export async function enableCodeBuddyAdapter(options = {}) {
+  const home = options.codeBuddyHome ?? defaultCodeBuddyHome();
+  const platform = options.platform ?? process.platform;
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const installPath = options.installPath ?? codeBuddyInstallPath(home);
+  const localPluginPath = marketplacePluginPath(home);
+  await rm(codeBuddyRuntimeObservationPath(memoraxCodeHome), { force: true });
+  await mkdir(dirname(installPath), { recursive: true });
+  await rm(installPath, { recursive: true, force: true });
+  await rm(legacyCodeBuddyInstallPath(home), { recursive: true, force: true });
+  await cp(ROOT, installPath, { recursive: true, force: true, filter: packageCopyFilter(ROOT) });
+  await materializeCommonRuntime(installPath);
+  await materializeCodeBuddyHookManifest(installPath, platform);
+  await writePackageMetadata(installPath, options.codeBuddyCommand, home);
+  await materializeCanonicalSkill(installPath);
+  await mkdir(dirname(localPluginPath), { recursive: true });
+  await rm(localPluginPath, { recursive: true, force: true });
+  await cp(ROOT, localPluginPath, { recursive: true, force: true, filter: packageCopyFilter(ROOT) });
+  await materializeCommonRuntime(localPluginPath);
+  await materializeCodeBuddyHookManifest(localPluginPath, platform);
+  await writePackageMetadata(localPluginPath, options.codeBuddyCommand, home);
+  await materializeCanonicalSkill(localPluginPath);
+  await writeMarketplaceManifest(home);
+  await updateKnownMarketplace(home, true);
+  await updateSettings(home, (settings) => {
+    settings.enabledPlugins = recordValue(settings.enabledPlugins);
+    settings.enabledPlugins[PLUGIN_ID] = true;
+  });
+  await updateLegacyRegistry(home, { installPath, enabled: true });
+  return { ok: true, action: "enable", runtime: "codebuddy", integration: "hooks", installed: true, enabled: true, codeBuddyHome: home, installPath, marketplace: MARKETPLACE_NAME, pluginId: PLUGIN_ID, marketplacePath: localPluginPath, codebuddyHooks: { ok: true, configured: true, runtimeObserved: false, status: "unverified" }, codebuddySkills: { ok: true, status: "installed", managed: true, memoraxCode: true, path: join(localPluginPath, "skills", "memorax-code", "SKILL.md") } };
+}
+
+export async function disableCodeBuddyAdapter(options = {}) {
+  const home = options.codeBuddyHome ?? defaultCodeBuddyHome();
+  const registryPath = installedRegistryPath(home);
+  const installed = await pathExists(marketplacePluginPath(home)) || await pathExists(codeBuddyInstallPath(home));
+  if (!installed) return { ok: true, action: "disable", runtime: "codebuddy", installed: false, enabled: false, codeBuddyHome: home, statePath: registryPath, marketplace: MARKETPLACE_NAME, pluginId: PLUGIN_ID };
+  await updateSettings(home, (settings) => {
+    settings.enabledPlugins = recordValue(settings.enabledPlugins);
+    settings.enabledPlugins[PLUGIN_ID] = false;
+  });
+  await updateLegacyRegistry(home, { installPath: codeBuddyInstallPath(home), enabled: false });
+  return { ok: true, action: "disable", runtime: "codebuddy", installed: true, enabled: false, codeBuddyHome: home, statePath: registryPath, marketplace: MARKETPLACE_NAME, pluginId: PLUGIN_ID };
+}
+
+export async function readCodeBuddyAdapterStatus(options = {}) {
+  const home = options.codeBuddyHome ?? defaultCodeBuddyHome();
+  const platform = options.platform ?? process.platform;
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const installPath = codeBuddyInstallPath(home);
+  const localPluginPath = marketplacePluginPath(home);
+  const settings = await readJsonRecord(codeBuddySettingsPath(home));
+  const known = await readJsonRecord(knownMarketplacesPath(home));
+  const installedRoots = [];
+  for (const root of [localPluginPath, installPath]) {
+    if (await pathExists(root)) installedRoots.push(root);
+  }
+  const installed = installedRoots.length > 0;
+  const skillPath = join(localPluginPath, "skills", "memorax-code", "SKILL.md");
+  const skillInstalled = await pathExists(skillPath);
+  const enabled = settings.enabledPlugins?.[PLUGIN_ID] === true;
+  const marketplaceReady = Boolean(known[MARKETPLACE_NAME]);
+  const hookConfigured = installedRoots.length > 0
+    && (await Promise.all(installedRoots.map((root) => codeBuddyHookManifestConfigured(root, platform)))).every(Boolean);
+  const observation = await readCodeBuddyRuntimeObservation(memoraxCodeHome);
+  const runtimeObserved = hookConfigured && observationMatches(observation, home, platform);
+  return { ok: true, action: "status", runtime: "codebuddy", integration: "hooks", installed, enabled, managed: installed && marketplaceReady, codeBuddyHome: home, installPath, marketplace: MARKETPLACE_NAME, pluginId: PLUGIN_ID, marketplaceReady, codebuddyHooks: { ok: hookConfigured, configured: hookConfigured, runtimeObserved, status: hookConfigured ? (runtimeObserved ? "observed" : "unverified") : "invalid", observationPath: codeBuddyRuntimeObservationPath(memoraxCodeHome) }, codebuddySkills: { ok: skillInstalled, status: skillInstalled ? "installed" : "missing", managed: skillInstalled, memoraxCode: skillInstalled, path: skillPath } };
+}
+
+export async function removeCodeBuddyPluginInstallation(options = {}) {
+  const home = options.codeBuddyHome ?? defaultCodeBuddyHome();
+  const installed = await pathExists(marketplacePluginPath(home)) || await pathExists(codeBuddyInstallPath(home));
+  if (!installed) return { ok: true, action: "codebuddy-plugin-remove", runtime: "codebuddy", installed: false, enabled: false, removed: false, codeBuddyHome: home, marketplace: MARKETPLACE_NAME, pluginId: PLUGIN_ID };
+  const status = await disableCodeBuddyAdapter({ codeBuddyHome: home });
+  await updateSettings(home, (settings) => {
+    settings.enabledPlugins = recordValue(settings.enabledPlugins);
+    delete settings.enabledPlugins[PLUGIN_ID];
+  });
+  await updateKnownMarketplace(home, false);
+  await updateRegistry(home, (registry) => { delete registry[PLUGIN_ID]; });
+  await rm(codeBuddyInstallPath(home), { recursive: true, force: true });
+  await rm(legacyCodeBuddyInstallPath(home), { recursive: true, force: true });
+  await rm(marketplaceRoot(home), { recursive: true, force: true });
+  return { ...status, action: "codebuddy-plugin-remove", installed: false, enabled: false, removed: true };
+}
+
+async function readRegistry(home) {
+  try {
+    const value = JSON.parse(await readFile(installedRegistryPath(home), "utf8"));
+    if (value?.plugins && typeof value.plugins === "object" && !Array.isArray(value.plugins)) return value.plugins;
+    throw new Error(`invalid CodeBuddy plugin registry: ${installedRegistryPath(home)}`);
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+}
+async function writeRegistry(home, plugins) { await writeJsonFile(installedRegistryPath(home), { version: 2, plugins }); }
+async function updateLegacyRegistry(home, { installPath, enabled }) {
+  await updateRegistry(home, (registry) => {
+    registry[PLUGIN_ID] = [{ scope: "user", installPath, version: VERSION, enabled, installedAt: new Date().toISOString(), lastUpdated: new Date().toISOString() }];
+  });
+}
+async function writeMarketplaceManifest(home) {
+  const path = join(marketplaceRoot(home), ".codebuddy-plugin", "marketplace.json");
+  await writeJsonFile(path, {
+    name: MARKETPLACE_NAME,
+    description: "MemoraX Code local integration marketplace",
+    plugins: [{ name: PLUGIN_NAME, source: `./plugins/${PLUGIN_NAME}`, version: VERSION, description: "MemoraX Code memory integration for CodeBuddy and WorkBuddy." }],
+  });
+}
+async function updateKnownMarketplace(home, enabled) {
+  const path = knownMarketplacesPath(home);
+  const known = await readJsonRecord(path);
+  if (enabled) {
+    known[MARKETPLACE_NAME] = {
+      type: "directory",
+      source: { source: "directory", path: marketplaceRoot(home) },
+      installLocation: marketplaceRoot(home),
+      description: "MemoraX Code local integration marketplace",
+      lastUpdated: new Date().toISOString(),
+      autoUpdate: false,
+    };
+  } else {
+    delete known[MARKETPLACE_NAME];
+  }
+  await writeJsonFile(path, known);
+}
+async function updateSettings(home, mutate) {
+  const path = codeBuddySettingsPath(home);
+  await updateJsonRecord(path, mutate);
+}
+
+async function updateRegistry(home, mutate) {
+  const path = installedRegistryPath(home);
+  await updateJsonRecord(path, (value) => {
+    value.version = 2;
+    value.plugins = recordValue(value.plugins);
+    mutate(value.plugins);
+  });
+}
+
+async function updateJsonRecord(path, mutate) {
+  const lockPath = `${path}.lock`;
+  await mkdir(dirname(path), { recursive: true });
+  let handle;
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try {
+      handle = await import("node:fs/promises").then(({ open }) => open(lockPath, "wx", 0o600));
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      await new Promise((resolve) => setTimeout(resolve, Math.min(50, 5 + attempt)));
+    }
+  }
+  if (!handle) throw new Error(`timed out acquiring lock: ${lockPath}`);
+  try {
+    const value = await readJsonRecord(path);
+    mutate(value);
+    await writeJsonFile(path, value);
+  } finally {
+    await handle.close();
+    await rm(lockPath, { force: true });
+  }
+}
+async function readJsonRecord(path) {
+  try {
+    const value = JSON.parse(await readFile(path, "utf8"));
+    if (value && typeof value === "object" && !Array.isArray(value)) return value;
+    throw new Error(`invalid JSON object: ${path}`);
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+}
+async function writeJsonFile(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  let mode = 0o600;
+  try { mode = (await stat(path)).mode & 0o777; } catch {}
+  const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { mode });
+  await chmod(temp, mode);
+  await rename(temp, path);
+}
+async function pathExists(path) { try { await stat(path); return true; } catch { return false; } }
+function recordValue(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+function readPluginVersion() {
+  const manifest = JSON.parse(readFileSync(join(ROOT, ".codebuddy-plugin", "plugin.json"), "utf8"));
+  if (typeof manifest?.version !== "string" || !manifest.version.trim()) {
+    throw new Error("MemoraX Code CodeBuddy plugin manifest has no version.");
+  }
+  return manifest.version.trim();
+}
+function legacyCodeBuddyInstallPath(home) { return join(home, "plugins", "cache", PLUGIN_NAME, VERSION); }
+
+async function materializeCanonicalSkill(destination) {
+  const packagedSkill = join(ROOT, "skills", "memorax-code");
+  const canonicalSkill = join(ROOT, "..", "memorax-code-codex-adapter", "skills", "memorax-code");
+  const source = await pathExists(packagedSkill) ? packagedSkill : canonicalSkill;
+  if (!await pathExists(source)) throw new Error(`MemoraX Code canonical skill is unavailable: ${source}`);
+  const target = join(destination, "skills", "memorax-code");
+  await rm(target, { recursive: true, force: true });
+  await mkdir(dirname(target), { recursive: true });
+  await cp(source, target, { recursive: true, force: true });
+}
+
+async function writePackageMetadata(destination, configuredCommand, codeBuddyHome) {
+  const codeBuddyCommand = typeof configuredCommand === "string" && configuredCommand.trim()
+    ? configuredCommand.trim()
+    : resolveHookCodeBuddyCommand();
+  await writeJsonFile(join(destination, ".memorax-code-package.json"), {
+    version: 1,
+    codeBuddyCommand,
+    codeBuddyHome,
+  });
+}
+
+async function materializeCommonRuntime(destination) {
+  const source = join(ROOT, "..", "memorax-code-adapter-common", "src");
+  const target = join(destination, "memorax-code-adapter-common", "src");
+  await rm(target, { recursive: true, force: true });
+  await mkdir(dirname(target), { recursive: true });
+  await cp(source, target, { recursive: true, force: true, filter: packageCopyFilter(source) });
+}
+
+function packageCopyFilter(root) {
+  return (source) => !relative(root, source).split(sep).some((part) => part === "test" || part === "node_modules");
+}
+
+function defaultMemoraxCodeHome() {
+  return process.env.MEMORAX_CODE_HOME?.trim() || join(homedir(), ".memorax-code");
+}
+
+function observationMatches(observation, codeBuddyHome, platform) {
+  if (observation?.pluginVersion !== VERSION) return false;
+  const left = comparablePath(observation.codeBuddyHome, platform);
+  const right = comparablePath(codeBuddyHome, platform);
+  return left === right;
+}
+
+function comparablePath(value, platform) {
+  const normalized = String(value ?? "").replaceAll("\\", "/").replace(/\/+$/, "");
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}

package/lib/memorax-code-codebuddy-adapter/src/hook-manifest.mjs

@@ -0,0 +1,47 @@
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { join, win32 } from "node:path";
+
+const REQUIRED_EVENTS = ["SessionStart", "UserPromptSubmit", "Stop"];
+const PORTABLE_COMMAND = 'node "${CODEBUDDY_PLUGIN_ROOT}/hooks/runtime-hook.mjs" turn';
+
+export function codeBuddyHookCommand(pluginRoot, platform = process.platform) {
+  if (platform !== "win32") return PORTABLE_COMMAND;
+  return `node "${win32.join(pluginRoot, "hooks", "runtime-hook.mjs").replaceAll("\\", "/")}" turn`;
+}
+
+export async function materializeCodeBuddyHookManifest(pluginRoot, platform = process.platform) {
+  if (platform !== "win32") return;
+  const path = join(pluginRoot, "hooks", "hooks.json");
+  const manifest = JSON.parse(await readFile(path, "utf8"));
+  const command = codeBuddyHookCommand(pluginRoot, platform);
+  for (const event of REQUIRED_EVENTS) {
+    const hooks = commandHooks(manifest, event);
+    if (hooks.length === 0) throw new Error(`CodeBuddy Hook manifest is missing ${event}`);
+    for (const hook of hooks) hook.command = command;
+  }
+  await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+export async function codeBuddyHookManifestConfigured(pluginRoot, platform = process.platform) {
+  try {
+    await stat(join(pluginRoot, "hooks", "runtime-hook.mjs"));
+    const manifest = JSON.parse(await readFile(join(pluginRoot, "hooks", "hooks.json"), "utf8"));
+    const expected = codeBuddyHookCommand(pluginRoot, platform);
+    return REQUIRED_EVENTS.every((event) => {
+      const hooks = commandHooks(manifest, event);
+      return hooks.length > 0 && hooks.every((hook) => hook.command === expected);
+    });
+  } catch {
+    return false;
+  }
+}
+
+function commandHooks(manifest, event) {
+  const matchers = manifest?.hooks?.[event];
+  if (!Array.isArray(matchers)) return [];
+  return matchers.flatMap((matcher) => (
+    Array.isArray(matcher?.hooks)
+      ? matcher.hooks.filter((hook) => hook?.type === "command" && typeof hook.command === "string")
+      : []
+  ));
+}