nexo-brain 5.3.28 → 5.3.30

package/src/scripts/nexo-update.sh

@@ -1,306 +1,32 @@
 #!/usr/bin/env bash
-# nexo-update.sh — Standalone NEXO update script
-# Same logic as the MCP tool but usable when the server itself needs updating.
-#
+# nexo-update.sh — Thin wrapper around the canonical Python update core.
 # Usage:
 #   nexo-update.sh                    # pull from origin main
 #   nexo-update.sh origin beta        # pull from origin beta
-#   NEXO_HOME=/path nexo-update.sh    # custom NEXO_HOME
 
 set -euo pipefail
 
-# --- Configuration ---
 REMOTE="${1:-origin}"
 BRANCH="${2:-main}"
-NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
-
-# Determine repo directory: script is at src/scripts/, repo root is ../../
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
-SRC_DIR="$REPO_DIR/src"
-PACKAGE_JSON="$REPO_DIR/package.json"
-
-# --- Helpers ---
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m'
-
-log()  { echo -e "${GREEN}[nexo-update]${NC} $*"; }
-warn() { echo -e "${YELLOW}[nexo-update]${NC} $*"; }
-err()  { echo -e "${RED}[nexo-update]${NC} $*" >&2; }
-
-read_version() {
-    python3 -c "import json; print(json.load(open('$PACKAGE_JSON')).get('version','unknown'))" 2>/dev/null || echo "unknown"
-}
-
-# --- Check if this is a git repo ---
-if [ ! -d "$REPO_DIR/.git" ] && [ ! -f "$REPO_DIR/.git" ]; then
-    err "ABORTED: Not a git repository at $REPO_DIR"
-    err "For packaged installs, use: npm update -g nexo-brain"
-    exit 1
-fi
-
-# --- Step 1: Check for uncommitted changes in entire worktree ---
-log "Checking for uncommitted changes..."
-cd "$REPO_DIR"
-
-if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
-    err "ABORTED: Uncommitted changes in worktree"
-    git status --short
-    exit 1
-fi
-log "Working tree clean."
-
-# Record current state
-OLD_VERSION="$(read_version)"
-OLD_COMMIT="$(git rev-parse HEAD)"
-REQ_FILE="$SRC_DIR/requirements.txt"
-OLD_REQ_HASH=""
-if [ -f "$REQ_FILE" ]; then
-    OLD_REQ_HASH="$(shasum -a 256 "$REQ_FILE" | cut -d' ' -f1)"
-fi
-log "Current: v${OLD_VERSION} (${OLD_COMMIT:0:8})"
-
-# --- Step 2: Backup databases ---
-TIMESTAMP="$(date +%Y-%m-%d-%H%M)"
-BACKUP_DIR="$NEXO_HOME/backups/pre-update-$TIMESTAMP"
-
-backup_dbs() {
-    local found=0
-    # Check data/, NEXO_HOME root, and src/ for .db files
-    for dir in "$NEXO_HOME/data" "$NEXO_HOME" "$SRC_DIR"; do
-        if [ -d "$dir" ]; then
-            for db in "$dir"/*.db; do
-                [ -f "$db" ] || continue
-                found=1
-                mkdir -p "$BACKUP_DIR"
-                cp "$db" "$BACKUP_DIR/$(basename "$db")"
-                log "  Backed up: $(basename "$db")"
-            done
-        fi
-    done
-    if [ "$found" -eq 0 ]; then
-        log "  No databases found to backup."
-    fi
-}
-
-log "Backing up databases..."
-backup_dbs
+SRC_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+RUNTIME_PYTHON="${NEXO_RUNTIME_PYTHON:-python3}"
 
-# --- Step 3: git pull ---
-log "Pulling from ${REMOTE}/${BRANCH}..."
-PULL_OUTPUT="$(git pull "$REMOTE" "$BRANCH" 2>&1)" || {
-    err "git pull failed:"
-    err "$PULL_OUTPUT"
-    exit 1
-}
-log "$PULL_OUTPUT"
+export NEXO_CODE="${NEXO_CODE:-$SRC_DIR}"
+export PYTHONPATH="$SRC_DIR${PYTHONPATH:+:$PYTHONPATH}"
 
-if echo "$PULL_OUTPUT" | grep -q "Already up to date"; then
-    log "Already up to date (v${OLD_VERSION}). Done."
-    exit 0
-fi
+"$RUNTIME_PYTHON" - "$REMOTE" "$BRANCH" <<'PY'
+from __future__ import annotations
 
-# --- Step 4: Check version ---
-NEW_VERSION="$(read_version)"
-log "New version: v${NEW_VERSION}"
-
-# --- Step 4b: Reinstall Python dependencies if requirements.txt changed ---
-NEW_REQ_HASH=""
-if [ -f "$REQ_FILE" ]; then
-    NEW_REQ_HASH="$(shasum -a 256 "$REQ_FILE" | cut -d' ' -f1)"
-fi
-
-DEPS_CHANGED=false
-if [ "$OLD_REQ_HASH" != "$NEW_REQ_HASH" ]; then
-    DEPS_CHANGED=true
-fi
-
-reinstall_pip_deps() {
-    local VENV_PIP="$NEXO_HOME/.venv/bin/pip"
-    if [ -f "$REQ_FILE" ]; then
-        if [ -x "$VENV_PIP" ]; then
-            "$VENV_PIP" install --quiet -r "$REQ_FILE" || return 1
-        else
-            python3 -m pip install --quiet -r "$REQ_FILE" --break-system-packages 2>/dev/null || return 1
-        fi
-    fi
-    return 0
-}
-
-if [ "$DEPS_CHANGED" = true ] || [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
-    log "Reinstalling Python dependencies..."
-    if ! reinstall_pip_deps; then
-        err "pip install failed! Rolling back..."
-        git reset --hard "$OLD_COMMIT"
-        reinstall_pip_deps || warn "pip rollback also had issues"
-        if [ -d "$BACKUP_DIR" ]; then
-            for db in "$BACKUP_DIR"/*.db; do
-                [ -f "$db" ] || continue
-                BASENAME="$(basename "$db")"
-                for candidate in "$NEXO_HOME/data/$BASENAME" "$NEXO_HOME/$BASENAME" "$SRC_DIR/$BASENAME"; do
-                    if [ -f "$candidate" ]; then
-                        cp "$db" "$candidate"
-                        warn "  Restored: $BASENAME"
-                        break
-                    fi
-                done
-            done
-        fi
-        err "Rolled back to ${OLD_COMMIT:0:8}. Databases restored."
-        exit 1
-    fi
-    log "Python dependencies updated."
-fi
-
-# --- Step 5: Run migrations if version changed ---
-if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
-    log "Version changed: ${OLD_VERSION} -> ${NEW_VERSION}"
-    log "Running migrations..."
-    if ! (cd "$SRC_DIR" && python3 -c "import db; db.init_db()" 2>&1); then
-        err "Migration failed! Rolling back..."
-        git reset --hard "$OLD_COMMIT"
-        # Reinstall pip deps from restored old requirements.txt
-        reinstall_pip_deps || warn "pip rollback also had issues"
-        # Restore DB backups
-        if [ -d "$BACKUP_DIR" ]; then
-            for db in "$BACKUP_DIR"/*.db; do
-                [ -f "$db" ] || continue
-                BASENAME="$(basename "$db")"
-                for candidate in "$NEXO_HOME/data/$BASENAME" "$NEXO_HOME/$BASENAME" "$SRC_DIR/$BASENAME"; do
-                    if [ -f "$candidate" ]; then
-                        cp "$db" "$candidate"
-                        warn "  Restored: $BASENAME"
-                        break
-                    fi
-                done
-            done
-        fi
-        err "Rolled back to ${OLD_COMMIT:0:8}. Databases and deps restored."
-        exit 1
-    fi
-    log "Migrations applied."
-else
-    log "Version unchanged (${OLD_VERSION}), skipping migrations."
-fi
-
-# --- Step 6: Verify import ---
-log "Verifying server.py import..."
-if ! (cd "$SRC_DIR" && python3 -c "import server" 2>&1); then
-    err "Import verification failed! Rolling back..."
-    git reset --hard "$OLD_COMMIT"
-    # Reinstall pip deps from restored old requirements.txt
-    reinstall_pip_deps || warn "pip rollback also had issues"
-    if [ -d "$BACKUP_DIR" ]; then
-        for db in "$BACKUP_DIR"/*.db; do
-            [ -f "$db" ] || continue
-            BASENAME="$(basename "$db")"
-            for candidate in "$NEXO_HOME/data/$BASENAME" "$NEXO_HOME/$BASENAME" "$SRC_DIR/$BASENAME"; do
-                if [ -f "$candidate" ]; then
-                    cp "$db" "$candidate"
-                    warn "  Restored: $BASENAME"
-                    break
-                fi
-            done
-        done
-    fi
-    err "Rolled back to ${OLD_COMMIT:0:8}. Databases and deps restored."
-    exit 1
-fi
-
-# --- Step 7: Sync hooks to NEXO_HOME ---
-HOOKS_SRC="$SRC_DIR/hooks"
-HOOKS_DEST="$NEXO_HOME/hooks"
-if [ -d "$HOOKS_SRC" ]; then
-    mkdir -p "$HOOKS_DEST"
-    SYNCED=0
-    for hook in "$HOOKS_SRC"/*.sh; do
-        [ -f "$hook" ] || continue
-        cp "$hook" "$HOOKS_DEST/$(basename "$hook")"
-        chmod 755 "$HOOKS_DEST/$(basename "$hook")"
-        SYNCED=$((SYNCED + 1))
-    done
-    if [ "$SYNCED" -gt 0 ]; then
-        log "Synced $SYNCED hook(s) to $HOOKS_DEST"
-    fi
-fi
+import sys
 
-# --- Step 8: Sync cron definitions with manifest ---
-CRON_SYNC="$SRC_DIR/crons/sync.py"
-CRON_SYNC_OK=false
-if [ -f "$CRON_SYNC" ]; then
-    log "Syncing cron definitions..."
-    if NEXO_HOME="$NEXO_HOME" NEXO_CODE="$SRC_DIR" python3 "$CRON_SYNC" 2>&1; then
-        log "Cron definitions synced."
-        CRON_SYNC_OK=true
-    else
-        warn "Cron sync failed (non-fatal). Installed manifest NOT refreshed to avoid divergence."
-    fi
-fi
+from plugins.update import handle_update
 
-# --- Step 8b: Refresh installed manifest for catchup/watchdog (only if sync succeeded) ---
-if $CRON_SYNC_OK && [ -d "$SRC_DIR/crons" ]; then
-    mkdir -p "$NEXO_HOME/crons"
-    cp -f "$SRC_DIR/crons/"*.json "$NEXO_HOME/crons/" 2>/dev/null
-    cp -f "$SRC_DIR/crons/"*.py "$NEXO_HOME/crons/" 2>/dev/null
-    log "Refreshed installed crons manifest."
-fi
 
-# --- Step 9: Sync shared client configs ---
-CLIENT_SYNC="$SRC_DIR/scripts/nexo-sync-clients.py"
-if [ -f "$CLIENT_SYNC" ]; then
-    log "Syncing shared client configs..."
-    CLIENT_SYNC_ARGS=()
-    if [ -f "$NEXO_HOME/config/schedule.json" ]; then
-        while IFS= read -r line; do
-            [ -n "$line" ] && CLIENT_SYNC_ARGS+=("--enabled-client" "$line")
-        done < <(
-            NEXO_HOME="$NEXO_HOME" NEXO_CODE="$SRC_DIR" python3 - <<'PY'
-import json
-import os
-import sys
-from pathlib import Path
+remote = sys.argv[1]
+branch = sys.argv[2]
+result = handle_update(remote=remote, branch=branch)
+print(result)
 
-sys.path.insert(0, os.environ["NEXO_CODE"])
-from client_preferences import normalize_client_preferences
-
-schedule_file = Path(os.environ["NEXO_HOME"]) / "config" / "schedule.json"
-schedule_payload = json.loads(schedule_file.read_text()) if schedule_file.exists() else {}
-prefs = normalize_client_preferences(schedule_payload)
-if prefs != {key: schedule_payload.get(key) for key in prefs}:
-    merged = dict(schedule_payload)
-    merged.update(prefs)
-    schedule_file.parent.mkdir(parents=True, exist_ok=True)
-    schedule_file.write_text(json.dumps(merged, indent=2, ensure_ascii=False) + "\n")
-enabled = [key for key, value in prefs.get("interactive_clients", {}).items() if value]
-if prefs.get("automation_enabled", True):
-    backend = prefs.get("automation_backend")
-    if backend and backend != "none" and backend not in enabled:
-        enabled.append(backend)
-for item in enabled:
-    print(item)
+raise SystemExit(1 if result.startswith(("ABORTED", "UPDATE FAILED")) else 0)
 PY
-        )
-    fi
-    if NEXO_HOME="$NEXO_HOME" NEXO_CODE="$SRC_DIR" python3 "$CLIENT_SYNC" --nexo-home "$NEXO_HOME" --runtime-root "$SRC_DIR" "${CLIENT_SYNC_ARGS[@]}" --json >/dev/null 2>&1; then
-        log "Shared client configs synced."
-    else
-        warn "Client config sync failed (non-fatal). Run 'nexo clients sync' later."
-    fi
-fi
-
-# --- Done ---
-echo ""
-log "========================================="
-log " UPDATE SUCCESSFUL"
-if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
-    log " Version: ${OLD_VERSION} -> ${NEW_VERSION}"
-else
-    log " Version: ${OLD_VERSION} (unchanged)"
-fi
-log " Branch: ${REMOTE}/${BRANCH}"
-log " Backup: ${BACKUP_DIR}"
-log "========================================="
-echo ""
-warn "MCP server restart needed to load new code."

package/src/server.py

@@ -72,6 +72,140 @@ def _shutdown_handler(signum, frame):
     sys.exit(0)
 
 
+def _resolved_nexo_home() -> str:
+    return os.environ.get("NEXO_HOME", os.path.join(os.path.expanduser("~"), ".nexo"))
+
+
+def _data_dir() -> str:
+    return os.path.join(_resolved_nexo_home(), "data")
+
+
+def _backup_dir() -> str:
+    return os.path.join(_resolved_nexo_home(), "backups")
+
+
+def _allow_fresh_db_on_corruption() -> bool:
+    value = str(os.environ.get("NEXO_ALLOW_FRESH_DB_ON_CORRUPTION", "") or "").strip().lower()
+    return value in {"1", "true", "yes", "on"}
+
+
+def _quarantine_corrupt_db_file(db_path: str) -> None:
+    if os.path.exists(db_path):
+        corrupt_path = db_path + ".corrupt"
+        os.rename(db_path, corrupt_path)
+        print(f"[NEXO] Corrupt DB moved to {os.path.basename(corrupt_path)}", file=sys.stderr)
+    for ext in (".db-wal", ".db-shm"):
+        wal_path = db_path.replace(".db", ext)
+        if os.path.exists(wal_path):
+            os.remove(wal_path)
+
+
+def _restore_valid_db_backup() -> bool:
+    import glob
+    import shutil
+    import sqlite3
+
+    from db._core import DB_PATH as db_path
+
+    backups = sorted(glob.glob(os.path.join(_backup_dir(), "nexo-*.db")), reverse=True)
+    for backup_path in backups:
+        try:
+            test_conn = sqlite3.connect(backup_path)
+            integrity = test_conn.execute("PRAGMA integrity_check").fetchone()
+            test_conn.close()
+            if not integrity or integrity[0] != "ok":
+                continue
+            try:
+                close_db()
+            except Exception:
+                pass
+            shutil.copy2(backup_path, db_path)
+            print(f"[NEXO] Restored DB from backup: {os.path.basename(backup_path)}", file=sys.stderr)
+            init_db()
+            return True
+        except Exception:
+            continue
+    return False
+
+
+def _init_db_or_exit() -> None:
+    import sqlite3
+
+    try:
+        init_db()
+        return
+    except sqlite3.DatabaseError as exc:
+        print(f"[NEXO] DB init failed: {exc}", file=sys.stderr)
+
+    restored = False
+    try:
+        restored = _restore_valid_db_backup()
+    except Exception as restore_exc:
+        print(f"[NEXO] Backup restore failed: {restore_exc}", file=sys.stderr)
+
+    if restored:
+        return
+
+    try:
+        close_db()
+    except Exception:
+        pass
+
+    try:
+        from db._core import DB_PATH as db_path
+        _quarantine_corrupt_db_file(db_path)
+    except Exception:
+        pass
+
+    if not _allow_fresh_db_on_corruption():
+        print(
+            "[NEXO] Refusing to create a fresh empty database automatically. "
+            "Restore a valid backup or set NEXO_ALLOW_FRESH_DB_ON_CORRUPTION=1 to override.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    try:
+        init_db()
+        print("[NEXO] Fresh database created because override is enabled.", file=sys.stderr)
+    except Exception as fresh_exc:
+        print(f"[NEXO] FATAL: Cannot initialize database: {fresh_exc}", file=sys.stderr)
+        print("[NEXO] Check permissions on NEXO_HOME/data/ and disk space.", file=sys.stderr)
+        sys.exit(1)
+
+
+def _emit_startup_preflight_messages(result: dict) -> None:
+    if result.get("updated"):
+        print("[NEXO] Startup update applied.", file=sys.stderr)
+    if result.get("deferred_reason"):
+        print(f"[NEXO] Startup update deferred: {result['deferred_reason']}", file=sys.stderr)
+    if result.get("git_update"):
+        print(f"[NEXO] {result['git_update']}", file=sys.stderr)
+    if result.get("npm_notice"):
+        print(f"[NEXO] {result['npm_notice']}", file=sys.stderr)
+    if result.get("claude_md_update"):
+        print(f"[NEXO] {result['claude_md_update']}", file=sys.stderr)
+    for message in result.get("client_bootstrap_updates", []):
+        if message != result.get("claude_md_update"):
+            print(f"[NEXO] {message}", file=sys.stderr)
+    for migration in result.get("migrations", []):
+        if migration.get("status") == "failed":
+            print(
+                f"[NEXO] Migration {migration.get('file', '?')} FAILED: {migration.get('message', '')}",
+                file=sys.stderr,
+            )
+
+
+def _run_startup_preflight_sync() -> None:
+    try:
+        from auto_update import startup_preflight
+
+        result = startup_preflight(entrypoint="server", interactive=False)
+        _emit_startup_preflight_messages(result)
+    except Exception as e:
+        print(f"[NEXO auto-update] error: {e}", file=sys.stderr)
+
+
 def _server_init():
     """Run all side effects: signals, PID, DB, auto-update, plugins.
 
@@ -81,110 +215,17 @@ def _server_init():
     signal.signal(signal.SIGINT, _shutdown_handler)
 
     # ── Write PID file for stale process detection ─────────────────
-    _data_dir = os.path.join(os.environ.get("NEXO_HOME", os.path.join(os.path.expanduser("~"), ".nexo")), "data")
-    os.makedirs(_data_dir, exist_ok=True)
-    _pid_file = os.path.join(_data_dir, "nexo.pid")
+    data_dir = _data_dir()
+    os.makedirs(data_dir, exist_ok=True)
+    _pid_file = os.path.join(data_dir, "nexo.pid")
     with open(_pid_file, "w") as f:
         f.write(str(os.getpid()))
 
     # ── Database initialization with recovery ─────────────────────
-    import sqlite3
-    try:
-        init_db()
-    except sqlite3.DatabaseError as exc:
-        # Corruption or unreadable DB — attempt restore from backup
-        print(f"[NEXO] DB init failed: {exc}", file=sys.stderr)
-        _recovered = False
-        try:
-            from db._core import DB_PATH as _db_path
-            import glob as _glob
-            _backup_dir = os.path.join(
-                os.environ.get("NEXO_HOME", os.path.join(os.path.expanduser("~"), ".nexo")),
-                "backups",
-            )
-            _backups = sorted(_glob.glob(os.path.join(_backup_dir, "nexo-*.db")), reverse=True)
-            for _bk in _backups:
-                try:
-                    _test = sqlite3.connect(_bk)
-                    _result = _test.execute("PRAGMA integrity_check").fetchone()
-                    _test.close()
-                    if _result and _result[0] == "ok":
-                        # Valid backup found — replace corrupt DB
-                        import shutil
-                        # Close any open connection before replacing
-                        try:
-                            close_db()
-                        except Exception:
-                            pass
-                        shutil.copy2(_bk, _db_path)
-                        print(f"[NEXO] Restored DB from backup: {os.path.basename(_bk)}", file=sys.stderr)
-                        init_db()
-                        _recovered = True
-                        break
-                except Exception:
-                    continue
-        except Exception as restore_exc:
-            print(f"[NEXO] Backup restore failed: {restore_exc}", file=sys.stderr)
-
-        if not _recovered:
-            # No valid backup — nuke corrupt file and start fresh
-            try:
-                close_db()
-            except Exception:
-                pass
-            try:
-                from db._core import DB_PATH as _db_path
-                if os.path.exists(_db_path):
-                    _corrupt_path = _db_path + ".corrupt"
-                    os.rename(_db_path, _corrupt_path)
-                    print(f"[NEXO] Corrupt DB moved to {os.path.basename(_corrupt_path)}", file=sys.stderr)
-                # Remove WAL/SHM files too
-                for _ext in (".db-wal", ".db-shm"):
-                    _wal = _db_path.replace(".db", _ext)
-                    if os.path.exists(_wal):
-                        os.remove(_wal)
-            except Exception:
-                pass
-            try:
-                init_db()
-                print("[NEXO] Fresh database created.", file=sys.stderr)
-            except Exception as fresh_exc:
-                print(f"[NEXO] FATAL: Cannot initialize database: {fresh_exc}", file=sys.stderr)
-                print("[NEXO] Check permissions on NEXO_HOME/data/ and disk space.", file=sys.stderr)
-                sys.exit(1)
-
-    # ── Auto-update check (non-blocking, max 5s) ──────────────────
-    try:
-        from auto_update import startup_preflight
-        import threading
+    _init_db_or_exit()
 
-        def _bg_update():
-            try:
-                result = startup_preflight(entrypoint="server", interactive=False)
-                if result.get("updated"):
-                    print("[NEXO] Startup update applied.", file=sys.stderr)
-                if result.get("deferred_reason"):
-                    print(f"[NEXO] Startup update deferred: {result['deferred_reason']}", file=sys.stderr)
-                if result.get("git_update"):
-                    print(f"[NEXO] {result['git_update']}", file=sys.stderr)
-                if result.get("npm_notice"):
-                    print(f"[NEXO] {result['npm_notice']}", file=sys.stderr)
-                if result.get("claude_md_update"):
-                    print(f"[NEXO] {result['claude_md_update']}", file=sys.stderr)
-                for message in result.get("client_bootstrap_updates", []):
-                    if message != result.get("claude_md_update"):
-                        print(f"[NEXO] {message}", file=sys.stderr)
-                for m in result.get("migrations", []):
-                    if m["status"] == "failed":
-                        print(f"[NEXO] Migration {m['file']} FAILED: {m['message']}", file=sys.stderr)
-            except Exception as e:
-                print(f"[NEXO auto-update] error: {e}", file=sys.stderr)
-
-        _update_thread = threading.Thread(target=_bg_update, daemon=True)
-        _update_thread.start()
-        _update_thread.join(timeout=5)  # Wait at most 5 seconds
-    except Exception:
-        pass  # Never break startup
+    # ── Auto-update / startup preflight (synchronous) ─────────────
+    _run_startup_preflight_sync()
 
     # ── Load plugins ───────────────────────────────────────────────
     load_all_plugins(mcp)

package/src/tree_hygiene.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+"""Shared tree hygiene helpers for runtime/install/release flows."""
+
+import re
+from pathlib import Path
+
+
+_DUPLICATE_COPY_RE = re.compile(r"^(?P<base>.+) (?P<copy>[2-9]\d*)$")
+_IGNORED_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    "node_modules",
+    "dist",
+    "build",
+}
+
+
+def canonical_artifact_name(name: str) -> str | None:
+    """Return the canonical sibling name for a macOS-style duplicate copy."""
+    path = Path(name)
+    match = _DUPLICATE_COPY_RE.match(path.stem)
+    if not match:
+        return None
+    return f"{match.group('base')}{path.suffix}"
+
+
+def is_duplicate_artifact_name(path_like: str | Path) -> bool:
+    """True when the path looks like a duplicate copy and its canonical sibling exists."""
+    path = Path(path_like)
+    canonical_name = canonical_artifact_name(path.name)
+    if canonical_name is None:
+        return False
+    parent = path.parent
+    if str(parent) in {"", "."} and not path.is_absolute():
+        return False
+    return path.with_name(canonical_name).exists()
+
+
+def find_duplicate_artifact_paths(root: str | Path) -> list[Path]:
+    """Find duplicate copy artifacts under a tree, skipping generated/vendor directories."""
+    root_path = Path(root).resolve()
+    duplicates: list[Path] = []
+    for path in sorted(root_path.rglob("*")):
+        if any(part in _IGNORED_DIRS for part in path.parts):
+            continue
+        if not path.is_file():
+            continue
+        if is_duplicate_artifact_name(path):
+            duplicates.append(path)
+    return duplicates