@trac3er/oh-my-god 2.2.3 → 2.2.5

package/build/lib/hooks/shadow_manager.py

@@ -1,476 +0,0 @@
-#!/usr/bin/env python3
-"""OMG v1 Shadow Manager
-
-Maintains overlay-style shadow writes and evidence artifacts.
-"""
-from __future__ import annotations
-
-import hashlib
-import importlib
-import json
-import os
-import platform
-import shutil
-import socket
-import sys
-from datetime import datetime, timezone
-from typing import Any
-
-HOOKS_DIR = os.path.dirname(__file__)
-if HOOKS_DIR not in sys.path:
-    sys.path.insert(0, HOOKS_DIR)
-try:
-    from hooks._common import _resolve_project_dir
-    from hooks.security_validators import ensure_path_within_dir, validate_opaque_identifier
-except ImportError:
-    _common = importlib.import_module("_common")
-    security_validators = importlib.import_module("security_validators")
-    _resolve_project_dir = _common._resolve_project_dir
-    ensure_path_within_dir = security_validators.ensure_path_within_dir
-    validate_opaque_identifier = security_validators.validate_opaque_identifier
-
-
-def _project_dir() -> str:
-    return _resolve_project_dir()
-
-
-def _shadow_root(project_dir: str) -> str:
-    return os.path.join(project_dir, ".omg", "shadow")
-
-
-def _evidence_root(project_dir: str) -> str:
-    return os.path.join(project_dir, ".omg", "evidence")
-
-
-def _active_run_path(project_dir: str) -> str:
-    return os.path.join(_shadow_root(project_dir), "active-run")
-
-
-def _utc_now() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def _new_run_id() -> str:
-    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
-
-
-def _validated_run_id(run_id: str) -> str:
-    return validate_opaque_identifier(run_id, "run_id")
-
-
-def _hash_file(path: str) -> str:
-    h = hashlib.sha256()
-    with open(path, "rb") as f:
-        while True:
-            chunk = f.read(8192)
-            if not chunk:
-                break
-            h.update(chunk)
-    return h.hexdigest()
-
-
-def ensure_shadow_dirs(project_dir: str) -> None:
-    os.makedirs(_shadow_root(project_dir), exist_ok=True)
-    os.makedirs(_evidence_root(project_dir), exist_ok=True)
-
-
-def set_active_run_id(project_dir: str, run_id: str) -> None:
-    ensure_shadow_dirs(project_dir)
-    run_id = _validated_run_id(run_id)
-    with open(_active_run_path(project_dir), "w", encoding="utf-8") as f:
-        f.write(run_id)
-
-
-def get_active_run_id(project_dir: str) -> str | None:
-    env_id = os.environ.get("OMG_RUN_ID")
-    if env_id:
-        return env_id
-    path = _active_run_path(project_dir)
-    if not os.path.exists(path):
-        return None
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            value = f.read().strip()
-            return value or None
-    except Exception:
-        return None
-
-
-def begin_shadow_run(project_dir: str, metadata: dict[str, Any] | None = None) -> str:
-    run_id = _validated_run_id(get_active_run_id(project_dir) or _new_run_id())
-    run_dir = os.path.join(_shadow_root(project_dir), run_id)
-    os.makedirs(run_dir, exist_ok=True)
-
-    manifest_path = os.path.join(run_dir, "manifest.json")
-    if not os.path.exists(manifest_path):
-        manifest = {
-            "run_id": run_id,
-            "created_at": _utc_now(),
-            "status": "open",
-            "files": [],
-            "metadata": metadata or {},
-        }
-        with open(manifest_path, "w", encoding="utf-8") as f:
-            json.dump(manifest, f, indent=2)
-
-    set_active_run_id(project_dir, run_id)
-    return run_id
-
-
-def _load_manifest(run_dir: str) -> dict[str, Any]:
-    path = os.path.join(run_dir, "manifest.json")
-    if not os.path.exists(path):
-        return {"files": []}
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            data = json.load(f)
-            if isinstance(data, dict):
-                data.setdefault("files", [])
-                return data
-            return {"files": []}
-    except Exception:
-        return {"files": []}
-
-
-def _save_manifest(run_dir: str, manifest: dict[str, Any]) -> None:
-    path = os.path.join(run_dir, "manifest.json")
-    manifest["updated_at"] = _utc_now()
-    with open(path, "w", encoding="utf-8") as f:
-        json.dump(manifest, f, indent=2)
-
-
-def map_shadow_path(project_dir: str, run_id: str, file_path: str) -> str:
-    run_id = _validated_run_id(run_id)
-    rel = os.path.relpath(os.path.abspath(file_path), os.path.abspath(project_dir))
-    rel = rel.replace("..", "_up_")
-    return os.path.join(_shadow_root(project_dir), run_id, "overlay", rel)
-
-
-def record_shadow_write(
-    project_dir: str,
-    run_id: str,
-    file_path: str,
-    source: str = "tool",
-    step_id: str | None = None,
-) -> dict[str, Any]:
-    run_id = _validated_run_id(run_id)
-    run_dir = os.path.join(_shadow_root(project_dir), run_id)
-    os.makedirs(run_dir, exist_ok=True)
-
-    shadow_path = map_shadow_path(project_dir, run_id, file_path)
-    os.makedirs(os.path.dirname(shadow_path), exist_ok=True)
-
-    abs_file = file_path if os.path.isabs(file_path) else os.path.join(project_dir, file_path)
-    file_existed_before = os.path.exists(abs_file)
-    if file_existed_before:
-        shutil.copy2(abs_file, shadow_path)
-        file_hash = _hash_file(abs_file)
-    else:
-        file_hash = ""
-
-    manifest = _load_manifest(run_dir)
-    rel = os.path.relpath(abs_file, project_dir)
-    entry = {
-        "file": rel,
-        "shadow_file": os.path.relpath(shadow_path, run_dir),
-        "recorded_at": _utc_now(),
-        "source": source,
-        "sha256": file_hash,
-        "file_existed_before": file_existed_before,
-    }
-    if step_id:
-        entry["step_id"] = step_id
-
-    files = manifest.get("files", [])
-    # Replace existing entry for same file.
-    files = [f for f in files if f.get("file") != rel]
-    files.append(entry)
-    manifest["files"] = files
-    _save_manifest(run_dir, manifest)
-
-    return entry
-
-
-def restore_shadow_entry(project_dir: str, run_id: str, step_id: str) -> dict[str, Any]:
-    run_id = _validated_run_id(run_id)
-    run_dir = os.path.join(_shadow_root(project_dir), run_id)
-    manifest = _load_manifest(run_dir)
-    entries = manifest.get("files", [])
-
-    restored: list[str] = []
-    failed: list[dict[str, str]] = []
-
-    selected_entries: list[dict[str, Any]] = []
-    for item in entries:
-        if not isinstance(item, dict):
-            continue
-        item_step_id = str(item.get("step_id", "")).strip()
-        if item_step_id == step_id:
-            selected_entries.append(item)
-
-    if not selected_entries and isinstance(entries, list) and len(entries) == 1:
-        single = entries[0]
-        if isinstance(single, dict):
-            selected_entries = [single]
-
-    if not selected_entries:
-        return {"restored": restored, "failed": failed, "reason": "step not found"}
-
-    for item in selected_entries:
-        rel = str(item.get("file", "")).strip()
-        shadow_rel = str(item.get("shadow_file", "")).strip()
-        file_existed_before = bool(item.get("file_existed_before", True))
-        if not rel:
-            failed.append({"file": "", "reason": "missing file path"})
-            continue
-
-        dst = os.path.join(project_dir, rel)
-        src = os.path.join(run_dir, shadow_rel) if shadow_rel else ""
-
-        if src and os.path.exists(src):
-            try:
-                os.makedirs(os.path.dirname(dst), exist_ok=True)
-                shutil.copy2(src, dst)
-                restored.append(rel)
-            except Exception as exc:
-                failed.append({"file": rel, "reason": f"copy failed: {exc}"})
-            continue
-
-        if not file_existed_before:
-            try:
-                if os.path.exists(dst):
-                    os.remove(dst)
-                restored.append(rel)
-            except Exception as exc:
-                failed.append({"file": rel, "reason": f"delete failed: {exc}"})
-            continue
-
-        failed.append({"file": rel, "reason": "shadow snapshot missing"})
-
-    manifest["status"] = "restored"
-    manifest["restored_at"] = _utc_now()
-    _save_manifest(run_dir, manifest)
-
-    reason = "shadow restore applied" if restored and not failed else "shadow restore partial"
-    if not restored and failed:
-        reason = "shadow restore failed"
-    return {"restored": restored, "failed": failed, "reason": reason}
-
-
-def create_evidence_pack(
-    project_dir: str,
-    run_id: str,
-    tests: list[dict[str, Any]] | None = None,
-    security_scans: list[dict[str, Any]] | None = None,
-    diff_summary: dict[str, Any] | None = None,
-    reproducibility: dict[str, Any] | None = None,
-    unresolved_risks: list[str] | None = None,
-    provenance: list[dict[str, Any]] | None = None,
-    trust_scores: dict[str, Any] | None = None,
-    api_twin: dict[str, Any] | None = None,
-    route_metadata: dict[str, Any] | None = None,
-    trace_ids: list[str] | None = None,
-    lineage: dict[str, Any] | None = None,
-    executor: dict[str, Any] | None = None,
-    environment: dict[str, Any] | None = None,
-    artifacts: list[dict[str, Any]] | None = None,
-    claims: list[dict[str, Any]] | None = None,
-    test_delta: dict[str, Any] | None = None,
-    browser_evidence_path: str | None = None,
-    repro_pack_path: str | None = None,
-) -> str:
-    ensure_shadow_dirs(project_dir)
-    run_id = _validated_run_id(run_id)
-    
-    # Default executor if not provided
-    if executor is None:
-        executor = {
-            "user": os.getenv("USER", "unknown"),
-            "pid": str(os.getpid()),
-        }
-    
-    # Default environment if not provided
-    if environment is None:
-        environment = {
-            "hostname": socket.gethostname(),
-            "platform": platform.system(),
-        }
-    
-    evidence = {
-        "schema": "EvidencePack",
-        "schema_version": 2,
-        "run_id": run_id,
-        "created_at": _utc_now(),
-        "tests": tests or [],
-        "security_scans": security_scans or [],
-        "diff_summary": diff_summary or {},
-        "reproducibility": reproducibility or {},
-        "unresolved_risks": unresolved_risks or [],
-        "provenance": provenance or [],
-        "trust_scores": trust_scores or {},
-        "api_twin": api_twin or {},
-        "route_metadata": route_metadata or {},
-        "trace_ids": trace_ids or [],
-        "lineage": lineage or {},
-        "executor": executor,
-        "environment": environment,
-        "artifacts": artifacts or [],
-    }
-    if claims is not None:
-        evidence["claims"] = claims
-    if test_delta is not None:
-        evidence["test_delta"] = test_delta
-    if browser_evidence_path is not None:
-        evidence["browser_evidence_path"] = browser_evidence_path
-    if repro_pack_path is not None:
-        evidence["repro_pack_path"] = repro_pack_path
-    evidence_path = ensure_path_within_dir(
-        _evidence_root(project_dir),
-        os.path.join(_evidence_root(project_dir), f"{run_id}.json"),
-    )
-    with open(evidence_path, "w", encoding="utf-8") as f:
-        json.dump(evidence, f, indent=2)
-    return evidence_path
-
-
-def has_recent_evidence(project_dir: str, hours: int = 24) -> bool:
-    ev_dir = _evidence_root(project_dir)
-    if not os.path.isdir(ev_dir):
-        return False
-
-    now = datetime.now(timezone.utc).timestamp()
-    max_age = hours * 3600
-
-    for name in os.listdir(ev_dir):
-        if not name.endswith(".json"):
-            continue
-        path = os.path.join(ev_dir, name)
-        try:
-            age = now - os.path.getmtime(path)
-            if age <= max_age:
-                return True
-        except OSError:
-            continue
-    return False
-
-
-def apply_shadow(project_dir: str, run_id: str) -> dict[str, Any]:
-    run_id = _validated_run_id(run_id)
-    run_dir = os.path.join(_shadow_root(project_dir), run_id)
-    manifest = _load_manifest(run_dir)
-    applied = []
-
-    for item in manifest.get("files", []):
-        rel = item.get("file")
-        shadow_rel = item.get("shadow_file")
-        if not rel or not shadow_rel:
-            continue
-        src = os.path.join(run_dir, shadow_rel)
-        dst = os.path.join(project_dir, rel)
-        if not os.path.exists(src):
-            continue
-        os.makedirs(os.path.dirname(dst), exist_ok=True)
-        shutil.copy2(src, dst)
-        applied.append(rel)
-
-    manifest["status"] = "applied"
-    manifest["applied_at"] = _utc_now()
-    _save_manifest(run_dir, manifest)
-
-    return {"run_id": run_id, "applied": applied}
-
-
-def drop_shadow(project_dir: str, run_id: str) -> dict[str, Any]:
-    run_id = _validated_run_id(run_id)
-    run_dir = os.path.join(_shadow_root(project_dir), run_id)
-    if os.path.isdir(run_dir):
-        print(f"[OMG] Deleting: {run_dir}", file=sys.stderr)
-        shutil.rmtree(run_dir, ignore_errors=True)
-
-    active = get_active_run_id(project_dir)
-    if active == run_id:
-        try:
-            os.remove(_active_run_path(project_dir))
-        except OSError:
-            pass
-
-    return {"run_id": run_id, "dropped": True}
-
-
-def auto_journal_mutation(
-    project_dir: str,
-    tool: str,
-    file_path: str,
-    run_id: str,
-) -> dict[str, Any] | None:
-    try:
-        from runtime.interaction_journal import InteractionJournal
-        from runtime.release_run_coordinator import resolve_current_run_id
-    except ImportError:
-        return None
-
-    canonical_run_id = resolve_current_run_id(project_dir) or run_id
-    shadow_manifest = os.path.join(
-        _shadow_root(project_dir), run_id, "manifest.json"
-    )
-
-    journal = InteractionJournal(project_dir)
-    return journal.record_step(
-        tool.lower(),
-        {
-            "file_path": file_path,
-            "run_id": canonical_run_id,
-            "shadow_manifest": shadow_manifest,
-        },
-    )
-
-
-def _handle_post_tool_use(payload: dict[str, Any]) -> None:
-    tool = payload.get("tool_name", "")
-    if tool not in ("Write", "Edit", "MultiEdit"):
-        return
-
-    tool_input = payload.get("tool_input", {}) if isinstance(payload.get("tool_input"), dict) else {}
-    file_path = tool_input.get("file_path", "")
-    if not file_path:
-        return
-
-    tool_resp = payload.get("tool_response", {})
-    success = None
-    if isinstance(tool_resp, dict):
-        success = tool_resp.get("success")
-
-    if success is False:
-        return
-
-    project_dir = _project_dir()
-    run_id = begin_shadow_run(project_dir, metadata={"source": "post-tool-use"})
-    record_shadow_write(project_dir, run_id, file_path)
-
-    try:
-        auto_journal_mutation(project_dir, tool, file_path, run_id)
-    except Exception:
-        pass
-
-
-def _main() -> int:
-    # Early-exit: skip all work if shadow/evidence mode is not enabled
-    project_dir = _project_dir()
-    policy_path = os.path.join(project_dir, ".omg", "policy.yaml")
-    if not os.path.exists(policy_path) and os.environ.get("OMG_EVIDENCE_REQUIRED", "0") != "1":
-        return 0
-
-    try:
-        payload = json.load(sys.stdin)
-    except Exception:
-        return 0
-
-    try:
-        _handle_post_tool_use(payload)
-    except Exception:
-        pass
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(_main())

package/build/lib/hooks/state_migration.py

@@ -1,228 +0,0 @@
-#!/usr/bin/env python3
-"""State path resolution and legacy `.omc` -> `.omg` migration utilities."""
-from __future__ import annotations
-
-from datetime import datetime, timezone
-import hashlib
-import json
-import os
-import shutil
-from typing import Any
-
-DEFAULT_MIGRATION_REPORT = "legacy-to-omg.json"
-LEGACY_MIGRATION_REPORT = "omc-to-omg.json"
-
-
-def paths(project_dir: str) -> dict[str, str]:
-    omg_root = os.path.join(project_dir, ".omg")
-    return {
-        "project": project_dir,
-        "omg_root": omg_root,
-        "omg_state": os.path.join(omg_root, "state"),
-        "omg_knowledge": os.path.join(omg_root, "knowledge"),
-        "omg_migrations": os.path.join(omg_root, "migrations"),
-        "legacy_omc": os.path.join(project_dir, ".omc"),
-    }
-
-
-def ensure_omg_structure(project_dir: str) -> None:
-    p = paths(project_dir)
-    os.makedirs(p["omg_state"], exist_ok=True)
-    os.makedirs(p["omg_knowledge"], exist_ok=True)
-    os.makedirs(p["omg_migrations"], exist_ok=True)
-
-
-def _sha256_file(path: str) -> str:
-    h = hashlib.sha256()
-    with open(path, "rb") as f:
-        while True:
-            chunk = f.read(8192)
-            if not chunk:
-                break
-            h.update(chunk)
-    return h.hexdigest()
-
-
-def _copy_file(src: str, dst: str) -> str:
-    os.makedirs(os.path.dirname(dst), exist_ok=True)
-    if os.path.exists(dst):
-        try:
-            if _sha256_file(src) == _sha256_file(dst):
-                return "unchanged"
-        except Exception:
-            pass
-    shutil.copy2(src, dst)
-    return "copied"
-
-
-def _copy_tree(src: str, dst: str) -> dict[str, int]:
-    stats = {"copied": 0, "unchanged": 0, "missing": 0, "errors": 0}
-    if not os.path.isdir(src):
-        stats["missing"] += 1
-        return stats
-    for root, _, files in os.walk(src):
-        for fn in files:
-            src_file = os.path.join(root, fn)
-            rel = os.path.relpath(src_file, src)
-            dst_file = os.path.join(dst, rel)
-            try:
-                status = _copy_file(src_file, dst_file)
-                stats[status] += 1
-            except Exception:
-                stats["errors"] += 1
-    return stats
-
-
-MIGRATION_MAP: list[tuple[str, str, str]] = [
-    ("file", "profile.yaml", "state/profile.yaml"),
-    ("file", "working-memory.md", "state/working-memory.md"),
-    ("file", "quality-gate.json", "state/quality-gate.json"),
-    ("file", "_plan.md", "state/_plan.md"),
-    ("file", "_checklist.md", "state/_checklist.md"),
-    ("file", "_context.md", "state/_context.md"),
-    ("file", "handoff.md", "state/handoff.md"),
-    ("file", "handoff.md.consumed", "state/handoff.md.consumed"),
-    ("file", "handoff-portable.md", "state/handoff-portable.md"),
-    # Legacy root-level runtime files used by older OMC installs.
-    ("file", "autopilot-state.json", "state/autopilot-state.json"),
-    ("file", "ultrapilot-state.json", "state/ultrapilot-state.json"),
-    ("file", "ralph-state.json", "state/ralph-state.json"),
-    ("file", "ultrawork-state.json", "state/ultrawork-state.json"),
-    ("file", "ultraqa-state.json", "state/ultraqa-state.json"),
-    ("file", "team-state.json", "state/team-state.json"),
-    ("file", "pipeline-state.json", "state/pipeline-state.json"),
-    ("file", "swarm-state.json", "state/swarm-state.json"),
-    ("file", "hud-state.json", "state/hud-state.json"),
-    ("file", "hud-stdin-cache.json", "state/hud-stdin-cache.json"),
-    ("file", "skill-active-state.json", "state/skill-active-state.json"),
-    ("file", "subagent-tracking.json", "state/subagent-tracking.json"),
-    # Runtime state files for HUD, routing, and session continuity.
-    ("file", "ecosystem-lock.json", "state/ecosystem-lock.json"),
-    ("file", "hashline_cache.json", "state/hashline_cache.json"),
-    ("file", "hashline_cache.json.tmp", "state/hashline_cache.json.tmp"),
-    ("file", "idle_signal.json", "state/idle_signal.json"),
-    ("file", "idle-notif-cooldown.json", "state/idle-notif-cooldown.json"),
-    ("file", "last-tool-error.json", "state/last-tool-error.json"),
-    ("file", "routing_result.json", "state/routing_result.json"),
-    ("file", "theme.json", "state/theme.json"),
-    ("file", "todo_progress.json", "state/todo_progress.json"),
-    # Migrate full runtime state for HUD + routing continuity.
-    ("dir", "state", "state"),
-    ("dir", "checkpoints", "state/checkpoints"),
-    ("dir", "ledger", "state/ledger"),
-    ("dir", "learnings", "state/learnings"),
-    ("dir", "memory", "state/memory"),
-    ("dir", "repl_sessions", "state/repl_sessions"),
-    ("dir", "sessions", "state/sessions"),
-    ("dir", "snapshots", "state/snapshots"),
-    ("file", "current_branch.json", "state/current_branch.json"),
-    ("file", "background-verification.json", "state/background-verification.json"),
-    ("dir", "branches", "state/branches"),
-    ("dir", "knowledge", "knowledge"),
-]
-
-
-def migrate_omc_to_omg(project_dir: str, force: bool = False) -> dict[str, Any]:
-    ensure_omg_structure(project_dir)
-    p = paths(project_dir)
-    legacy = p["legacy_omc"]
-    report: dict[str, Any] = {
-        "started_at": datetime.now(timezone.utc).isoformat(),
-        "project_dir": project_dir,
-        "legacy_path": legacy,
-        "target_path": p["omg_root"],
-        "result": "ok",
-        "entries": [],
-    }
-
-    if not os.path.isdir(legacy):
-        report["result"] = "no_legacy"
-    else:
-        for kind, src_rel, dst_rel in MIGRATION_MAP:
-            src = os.path.join(legacy, src_rel)
-            dst = os.path.join(p["omg_root"], dst_rel)
-            entry = {"kind": kind, "source": src_rel, "target": dst_rel, "status": "missing"}
-            try:
-                if kind == "file":
-                    if os.path.isfile(src):
-                        status = _copy_file(src, dst)
-                        entry["status"] = status
-                    else:
-                        entry["status"] = "missing"
-                else:
-                    stats = _copy_tree(src, dst)
-                    entry["status"] = "copied" if stats["copied"] else ("unchanged" if stats["unchanged"] else "missing")
-                    entry["stats"] = stats
-            except Exception as exc:
-                entry["status"] = "error"
-                entry["error"] = str(exc)
-                report["result"] = "partial_error"
-            report["entries"].append(entry)
-
-    report["finished_at"] = datetime.now(timezone.utc).isoformat()
-    os.makedirs(p["omg_migrations"], exist_ok=True)
-    out_path = os.path.join(p["omg_migrations"], DEFAULT_MIGRATION_REPORT)
-    legacy_out_path = os.path.join(p["omg_migrations"], LEGACY_MIGRATION_REPORT)
-
-    # idempotent write: overwrite with latest summary
-    for path in (out_path, legacy_out_path):
-        with open(path, "w", encoding="utf-8") as f:
-            json.dump(report, f, indent=2, ensure_ascii=True)
-    report["report_path"] = out_path
-    report["legacy_report_path"] = legacy_out_path
-    return report
-
-
-def migrate_legacy_to_omg(project_dir: str, force: bool = False) -> dict[str, Any]:
-    """Canonical migration API."""
-    return migrate_omc_to_omg(project_dir, force=force)
-
-
-def resolve_state_file(
-    project_dir: str,
-    omg_relative: str,
-    legacy_relative: str | None = None,
-    auto_migrate: bool = True,
-) -> str:
-    """Return preferred .omg file path; fallback to .omc if needed.
-
-    - If .omg target exists, return it.
-    - If not, and legacy exists, optionally run migration and return target if created.
-    - If still absent, return the preferred target path.
-    """
-    p = paths(project_dir)
-    preferred = os.path.join(p["omg_root"], omg_relative)
-    if os.path.exists(preferred):
-        return preferred
-
-    legacy_rel = legacy_relative or omg_relative
-    legacy_path = os.path.join(p["legacy_omc"], legacy_rel)
-    if os.path.exists(legacy_path) and auto_migrate:
-        migrate_legacy_to_omg(project_dir)
-        if os.path.exists(preferred):
-            return preferred
-    if os.path.exists(legacy_path):
-        return legacy_path
-    return preferred
-
-
-def resolve_state_dir(
-    project_dir: str,
-    omg_relative: str,
-    legacy_relative: str | None = None,
-    auto_migrate: bool = True,
-) -> str:
-    p = paths(project_dir)
-    preferred = os.path.join(p["omg_root"], omg_relative)
-    if os.path.isdir(preferred):
-        return preferred
-
-    legacy_rel = legacy_relative or omg_relative
-    legacy_path = os.path.join(p["legacy_omc"], legacy_rel)
-    if os.path.isdir(legacy_path) and auto_migrate:
-        migrate_legacy_to_omg(project_dir)
-        if os.path.isdir(preferred):
-            return preferred
-    if os.path.isdir(legacy_path):
-        return legacy_path
-    return preferred