@memorax/memorax-code 0.1.2 → 0.1.3

package/lib/memorax-code-opencode-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-opencode-adapter/src/adapter-paths.mjs

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export function defaultOpenCodeConfigDir(env = process.env, home = homedir()) {
+  const explicit = stringOption(env.OPENCODE_CONFIG_DIR);
+  if (explicit) return resolve(explicit);
+  const configHome = stringOption(env.XDG_CONFIG_HOME) ?? join(home, ".config");
+  return resolve(configHome, "opencode");
+}
+
+export function defaultMemoraxCodeHome(env = process.env, home = homedir()) {
+  return resolve(stringOption(env.MEMORAX_CODE_HOME) ?? join(home, ".memorax-code"));
+}
+
+export function adapterStatePath(memoraxCodeHome = defaultMemoraxCodeHome()) {
+  return join(memoraxCodeHome, "adapters", "opencode", "state.json");
+}
+
+export function openCodeWorkspaceStatePath(memoraxCodeHome = defaultMemoraxCodeHome()) {
+  return join(memoraxCodeHome, "adapters", "opencode", "workspaces.json");
+}
+
+export function openCodePluginPath(configDir = defaultOpenCodeConfigDir()) {
+  return join(configDir, "plugins", "memorax-code.js");
+}
+
+export function openCodeSkillPath(configDir = defaultOpenCodeConfigDir()) {
+  return join(configDir, "skills", "memorax-code");
+}
+
+export function openCodeRepoMemoryHelperPath(configDir = defaultOpenCodeConfigDir()) {
+  return join(configDir, "hooks", "repo-memory-job.mjs");
+}
+
+function stringOption(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

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

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+import { resolveBackendConnection } from "../../memorax-code-adapter-common/src/backend-connection.mjs";
+import {
+  defaultMemoraxCodeHome,
+  defaultOpenCodeConfigDir,
+} from "./adapter-paths.mjs";
+import { readOpenCodeWorkspaceStatus } from "./diagnostics.mjs";
+import { readOpenCodePluginStatus } from "./plugin-install.mjs";
+
+const DEFAULT_TOKEN_ENV = "MEMORAX_CODE_BACKEND_TOKEN";
+const BACKEND_HEALTH_TIMEOUT_MS = 5_000;
+const VALUE_OPTIONS = new Set([
+  "--opencode-config-dir",
+  "--memorax-code-home",
+  "--backend-url",
+  "--backend-token-env",
+]);
+
+try {
+  const parsed = parseCli(process.argv);
+  if (parsed.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const options = parsed.options;
+  if (parsed.command === "status") {
+    print(openCodeStatus(options), options);
+  } else if (parsed.command === "doctor") {
+    const [status, workspace, backend] = await Promise.all([
+      openCodeStatus(options),
+      readOpenCodeWorkspaceStatus(options),
+      backendHealth(options.backendUrl, backendToken(options)),
+    ]);
+    print({
+      ok: status.ok && workspace.ok && workspace.captured && backend.ok,
+      action: "doctor",
+      status,
+      workspace,
+      backend,
+    }, options);
+  } else {
+    throw new Error(`unknown command: ${parsed.command}`);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function printHelp() {
+  console.log([
+    "Usage: memorax-code-opencode [status|doctor] [options]",
+    "",
+    "Lifecycle note: use `memorax-code start --clients opencode` to install or reconcile the OpenCode plugin.",
+    "",
+    "Options:",
+    "  --opencode-config-dir DIR  OpenCode config root (default: OPENCODE_CONFIG_DIR, XDG_CONFIG_HOME/opencode, or ~/.config/opencode)",
+    "  --memorax-code-home DIR    MemoraX Code state home (default: MEMORAX_CODE_HOME or ~/.memorax-code)",
+    "  --backend-url URL           Local Backend URL (default: persisted connection or http://127.0.0.1:8787)",
+    "  --backend-token-env NAME    Token env var for Backend health checks",
+    "  --json                      Print machine-readable JSON",
+  ].join("\n"));
+}
+
+function parseCli(argv) {
+  const args = argv.slice(2);
+  const first = args[0];
+  const command = first && !first.startsWith("-") ? first : "status";
+  const optionArgs = command === first ? args.slice(1) : args;
+  const help = command === "help" || optionArgs.includes("--help");
+  return {
+    command,
+    help,
+    options: help ? {} : parseOptions(optionArgs),
+  };
+}
+
+function parseOptions(args) {
+  const values = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json" || arg === "--help") {
+      values[arg] = true;
+      continue;
+    }
+    if (VALUE_OPTIONS.has(arg)) {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} requires a value`);
+      values[arg] = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) throw new Error(`unknown option: ${arg}`);
+    throw new Error(`unexpected argument: ${arg}`);
+  }
+
+  const memoraxCodeHome = values["--memorax-code-home"] ?? defaultMemoraxCodeHome();
+  const requestedBackendUrl = values["--backend-url"] ?? process.env.MEMORAX_CODE_BACKEND_URL;
+  if (requestedBackendUrl) validateHttpUrl(requestedBackendUrl, "--backend-url");
+  const connection = resolveBackendConnection({
+    memoraxCodeHome,
+    backendUrl: values["--backend-url"],
+  });
+  return {
+    openCodeConfigDir: values["--opencode-config-dir"] ?? defaultOpenCodeConfigDir(),
+    memoraxCodeHome,
+    backendUrl: connection.url,
+    backendTokenEnv: values["--backend-token-env"],
+    connection,
+    json: Boolean(values["--json"]),
+  };
+}
+
+function openCodeStatus(options) {
+  const status = readOpenCodePluginStatus(options);
+  const openCodeConfigDir = typeof status.state?.openCodeConfigDir === "string"
+    ? status.state.openCodeConfigDir
+    : options.openCodeConfigDir;
+  const ready = status.ok === true
+    && status.installed === true
+    && status.enabled === true
+    && status.current === true
+    && status.backendUrlMatches !== false
+    && status.opencodeSkills?.ok === true;
+  return {
+    ...status,
+    ok: ready,
+    action: "status",
+    openCodeConfigDir,
+    ...(openCodeConfigDir !== options.openCodeConfigDir
+      ? { requestedOpenCodeConfigDir: options.openCodeConfigDir }
+      : {}),
+    memoraxCodeHome: options.memoraxCodeHome,
+  };
+}
+
+function validateHttpUrl(value, optionName) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("unsupported protocol");
+  } catch {
+    throw new Error(`${optionName} must be an http(s) URL`);
+  }
+}
+
+async function backendHealth(backendUrl, token) {
+  try {
+    const headers = {
+      connection: "close",
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+    };
+    const response = await fetch(new URL("/health", backendUrl), {
+      headers,
+      signal: AbortSignal.timeout(BACKEND_HEALTH_TIMEOUT_MS),
+    });
+    const body = await response.json().catch(() => undefined);
+    return {
+      ok: response.ok && body?.ok === true && body?.service === "memorax-code-backend",
+      status: response.status,
+      body,
+    };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function backendToken(options) {
+  const tokenEnv = options.backendTokenEnv ?? DEFAULT_TOKEN_ENV;
+  return tokenEnv === DEFAULT_TOKEN_ENV
+    ? options.connection.token
+    : process.env[tokenEnv];
+}
+
+function print(result, options) {
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.action === "doctor") {
+    printDoctor(result);
+  } else {
+    printStatus(result);
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function printStatus(result, includeHints = true) {
+  console.log(`status: ${result.ok ? "ok" : "needs attention"}`);
+  console.log(`opencode config: ${result.openCodeConfigDir}`);
+  if (result.requestedOpenCodeConfigDir) {
+    console.log(`requested opencode config: ${result.requestedOpenCodeConfigDir}`);
+  }
+  console.log(`memorax-code home: ${result.memoraxCodeHome}`);
+  console.log(`state: ${result.statePath}`);
+  console.log("integration: plugin");
+  console.log("provider config: unchanged (OpenCode-owned)");
+  console.log(`managed plugin: ${check(result.pluginExists && result.pluginCurrent)}`);
+  console.log(`memorax-code skill: ${check(result.skillExists && result.skillCurrent)}`);
+  console.log(`repo-memory helper: ${check(result.repoMemoryHelperExists && result.repoMemoryHelperCurrent)}`);
+  console.log(`backend endpoint: ${check(result.backendUrlMatches !== false)} configured=${result.configuredBackendUrl ?? "missing"} expected=${result.expectedBackendUrl ?? "unknown"}`);
+  if (includeHints) printHints(statusHints(result));
+}
+
+function printDoctor(result) {
+  console.log(`doctor: ${result.ok ? "ok" : "needs attention"}`);
+  printStatus(result.status, false);
+  console.log(`plugin runtime evidence: ${check(result.workspace?.captured === true)}${workspaceDetail(result.workspace)}`);
+  console.log(`backend health: ${check(result.backend?.ok === true)}${backendDetail(result.backend)}`);
+  printHints(doctorHints(result));
+}
+
+function check(ok) {
+  return ok ? "ok" : "not ok";
+}
+
+function workspaceDetail(workspace) {
+  if (!workspace) return " missing";
+  if (workspace.ok === false) return ` ${workspace.reason ?? "invalid"} (${workspace.path})`;
+  if (!workspace.captured) return ` not observed (${workspace.path})`;
+  const latest = workspace.latest;
+  const event = typeof latest?.event === "string" ? ` event=${latest.event}` : "";
+  const cwd = typeof latest?.cwd === "string" ? ` cwd=${latest.cwd}` : "";
+  const capturedAt = typeof latest?.capturedAt === "string" ? ` at=${latest.capturedAt}` : "";
+  return `${event}${cwd}${capturedAt}`;
+}
+
+function backendDetail(backend) {
+  if (!backend) return " missing";
+  if (backend.ok) return backend.status ? ` status=${backend.status}` : "";
+  return ` ${backend.error ?? backend.status ?? "not reachable"}`;
+}
+
+function statusHints(result) {
+  const hints = [];
+  if (result.installed !== true || result.enabled !== true || result.current !== true) {
+    hints.push("Install or reconcile the managed integration with `memorax-code start --clients opencode`, then restart or refresh OpenCode.");
+  }
+  if (result.backendUrlMatches === false) {
+    hints.push("Adapter state points at a different Backend endpoint; rerun `memorax-code start --clients opencode`.");
+  }
+  return hints;
+}
+
+function doctorHints(result) {
+  const hints = [...statusHints(result.status)];
+  if (result.backend?.ok !== true) {
+    hints.push("Backend is not reachable; start it with `memorax-code start` or pass the correct `--backend-url`.");
+  }
+  if (result.workspace?.ok === false) {
+    hints.push("OpenCode runtime evidence is unreadable or invalid; inspect or remove that state file, then restart or refresh OpenCode.");
+  } else if (result.workspace?.captured !== true) {
+    hints.push("No OpenCode plugin runtime has been observed yet; restart or refresh OpenCode, then rerun this command.");
+  }
+  return [...new Set(hints)];
+}
+
+function printHints(hints) {
+  if (hints.length === 0) return;
+  console.log("");
+  console.log("Recommended next steps:");
+  for (const hint of hints) console.log(`- ${hint}`);
+}

package/lib/memorax-code-opencode-adapter/src/diagnostics.mjs

@@ -0,0 +1,31 @@
+import { readAdapterState } from "../../memorax-code-adapter-common/src/config-utils.mjs";
+import {
+  defaultMemoraxCodeHome,
+  openCodeWorkspaceStatePath,
+} from "./adapter-paths.mjs";
+
+export function readOpenCodeWorkspaceStatus(options = {}) {
+  const memoraxCodeHome = options.memoraxCodeHome ?? defaultMemoraxCodeHome();
+  const path = options.workspaceStatePath ?? openCodeWorkspaceStatePath(memoraxCodeHome);
+  const state = readAdapterState(path);
+  const stateValid = !state || (
+    state.unreadable !== true
+    && state.version === 1
+    && state.runtime === "opencode"
+  );
+  const latest = stateValid && state?.latest && typeof state.latest === "object"
+    ? state.latest
+    : undefined;
+  return {
+    ok: stateValid,
+    action: "workspace-status",
+    memoraxCodeHome,
+    path,
+    captured: Boolean(latest?.cwd),
+    latest,
+    state,
+    ...(!stateValid
+      ? { reason: state?.unreadable ? "state_unreadable" : "state_invalid" }
+      : {}),
+  };
+}