nexo-brain 6.4.0 → 7.0.0

package/src/paths.py

@@ -0,0 +1,394 @@
+"""Plan Consolidado F0.6 — canonical path helpers.
+
+Every module that needs to find a runtime directory should import from
+here instead of hardcoding `NEXO_HOME / "scripts"` etc. The legacy
+flat layout (`~/.nexo/scripts/`, `~/.nexo/brain/`, `~/.nexo/data/`,
+...) is going away in v7.0.0; this module centralises the new tree
+so the migration is a one-line change per call site.
+
+New structure (post-F0.6):
+    ~/.nexo/
+    ├── core/                  ← shipped with the package
+    │   ├── scripts/           (38 packaged automations)
+    │   ├── plugins/
+    │   ├── hooks/
+    │   ├── rules/
+    │   └── contracts/         (resonance_tiers.json, ...)
+    ├── core-dev/              ← dev-only, off by default
+    │   └── scripts/
+    ├── personal/              ← operator. nexo update never touches.
+    │   ├── scripts/
+    │   ├── skills/
+    │   ├── plugins/
+    │   ├── hooks/
+    │   ├── rules/
+    │   ├── brain/             (calibration.json, project-atlas.json,
+    │   │                       operator-routing-rules.json, ...)
+    │   ├── config/
+    │   ├── lib/
+    │   └── overrides/
+    └── runtime/               ← dynamic state
+        ├── data/              (nexo.db, *.db)
+        ├── logs/
+        ├── operations/
+        ├── backups/
+        ├── memory/
+        ├── cognitive/
+        ├── coordination/
+        ├── exports/
+        ├── nexo-email/
+        ├── doctor/
+        ├── snapshots/
+        └── crons/
+
+Backwards compatibility: every helper has `legacy=True` mode that
+returns the pre-F0.6 location (`NEXO_HOME / "<name>"`). The compat
+layer disappears in v7.1.0; v7.0.0 keeps it so operator-edited code
+that hardcoded the old paths keeps resolving via symlink during the
+1-week observation window.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+
+def home() -> Path:
+    """Return the active NEXO_HOME (recomputed every call so tests
+    that monkeypatch the env var see the right path)."""
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+
+# ---------------------------------------------------------------------------
+# Core (shipped with the package, replaced on every `nexo update`)
+# ---------------------------------------------------------------------------
+def core_dir() -> Path:
+    return home() / "core"
+
+
+def core_scripts_dir() -> Path:
+    new = core_dir() / "scripts"
+    legacy = home() / "scripts"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def core_plugins_dir() -> Path:
+    new = core_dir() / "plugins"
+    legacy = home() / "plugins"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def core_hooks_dir() -> Path:
+    new = core_dir() / "hooks"
+    legacy = home() / "hooks"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def core_rules_dir() -> Path:
+    new = core_dir() / "rules"
+    legacy = home() / "rules"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def core_contracts_dir() -> Path:
+    return core_dir() / "contracts"
+
+
+# ---------------------------------------------------------------------------
+# Core-dev (off by default, only useful to product devs)
+# ---------------------------------------------------------------------------
+def core_dev_dir() -> Path:
+    return home() / "core-dev"
+
+
+def core_dev_scripts_dir() -> Path:
+    return core_dev_dir() / "scripts"
+
+
+# ---------------------------------------------------------------------------
+# Personal (operator-owned, `nexo update` never touches)
+# ---------------------------------------------------------------------------
+def personal_dir() -> Path:
+    return home() / "personal"
+
+
+def personal_scripts_dir() -> Path:
+    return personal_dir() / "scripts"
+
+
+def personal_plugins_dir() -> Path:
+    return personal_dir() / "plugins"
+
+
+def personal_hooks_dir() -> Path:
+    return personal_dir() / "hooks"
+
+
+def personal_rules_dir() -> Path:
+    return personal_dir() / "rules"
+
+
+def personal_skills_dir() -> Path:
+    new = personal_dir() / "skills"
+    legacy = home() / "skills"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def brain_dir() -> Path:
+    """Operator brain: calibration, project atlas, routing rules, ..."""
+    new = personal_dir() / "brain"
+    legacy = home() / "brain"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def personal_config_dir() -> Path:
+    return personal_dir() / "config"
+
+
+def personal_lib_dir() -> Path:
+    return personal_dir() / "lib"
+
+
+def personal_overrides_dir() -> Path:
+    return personal_dir() / "overrides"
+
+
+# ---------------------------------------------------------------------------
+# Runtime (dynamic state, never edited by hand)
+# ---------------------------------------------------------------------------
+def runtime_dir() -> Path:
+    return home() / "runtime"
+
+
+def data_dir() -> Path:
+    new = runtime_dir() / "data"
+    legacy = home() / "data"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def db_path() -> Path:
+    new = data_dir() / "nexo.db"
+    legacy = home() / "data" / "nexo.db"
+    if not new.is_file() and legacy.is_file():
+        return legacy
+    return new
+
+
+def logs_dir() -> Path:
+    new = runtime_dir() / "logs"
+    legacy = home() / "logs"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def operations_dir() -> Path:
+    new = runtime_dir() / "operations"
+    legacy = home() / "operations"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def backups_dir() -> Path:
+    new = runtime_dir() / "backups"
+    legacy = home() / "backups"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def memory_dir() -> Path:
+    new = runtime_dir() / "memory"
+    legacy = home() / "memory"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def cognitive_dir() -> Path:
+    new = runtime_dir() / "cognitive"
+    legacy = home() / "cognitive"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def coordination_dir() -> Path:
+    new = runtime_dir() / "coordination"
+    legacy = home() / "coordination"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def exports_dir() -> Path:
+    new = runtime_dir() / "exports"
+    legacy = home() / "exports"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def nexo_email_dir() -> Path:
+    new = runtime_dir() / "nexo-email"
+    legacy = home() / "nexo-email"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def doctor_dir() -> Path:
+    new = runtime_dir() / "doctor"
+    legacy = home() / "doctor"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def snapshots_dir() -> Path:
+    new = runtime_dir() / "snapshots"
+    legacy = home() / "snapshots"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+def crons_dir() -> Path:
+    new = runtime_dir() / "crons"
+    legacy = home() / "crons"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
+# ---------------------------------------------------------------------------
+# Combined views (for callers that need to scan core+personal merged)
+# ---------------------------------------------------------------------------
+def all_scripts_dirs() -> list[Path]:
+    """Return every directory `nexo scripts list` should scan."""
+    return [core_scripts_dir(), personal_scripts_dir(), core_dev_scripts_dir()]
+
+
+def all_plugins_dirs() -> list[Path]:
+    return [core_plugins_dir(), personal_plugins_dir()]
+
+
+def all_hooks_dirs() -> list[Path]:
+    return [core_hooks_dir(), personal_hooks_dir()]
+
+
+def all_rules_dirs() -> list[Path]:
+    return [core_rules_dir(), personal_rules_dir()]
+
+
+# ---------------------------------------------------------------------------
+# Legacy compat (PRE-F0.6 paths). Every shipped runtime keeps these as
+# symlinks to the new locations until v7.1.0, so operator code that
+# hardcoded the flat layout continues to resolve.
+# ---------------------------------------------------------------------------
+def legacy_scripts_dir() -> Path:
+    return home() / "scripts"
+
+
+def legacy_brain_dir() -> Path:
+    return home() / "brain"
+
+
+def legacy_data_dir() -> Path:
+    return home() / "data"
+
+
+def legacy_logs_dir() -> Path:
+    return home() / "logs"
+
+
+def legacy_operations_dir() -> Path:
+    return home() / "operations"
+
+
+def legacy_db_path() -> Path:
+    return legacy_data_dir() / "nexo.db"
+
+
+# ---------------------------------------------------------------------------
+# Smart resolver: prefer new location if it exists, fall back to legacy.
+# Used during the v7.0.0 / v7.1.0 transition window.
+# ---------------------------------------------------------------------------
+def resolve_db_path() -> Path:
+    """Return the active SQLite DB path, preferring the new location
+    but falling back to the legacy one when an older runtime hasn't
+    migrated yet."""
+    new = db_path()
+    if new.is_file():
+        return new
+    legacy = legacy_db_path()
+    if legacy.is_file():
+        return legacy
+    return new  # default: new layout for fresh installs
+
+
+__all__ = [
+    "NEXO_HOME",
+    "home",
+    "core_dir",
+    "core_scripts_dir",
+    "core_plugins_dir",
+    "core_hooks_dir",
+    "core_rules_dir",
+    "core_contracts_dir",
+    "core_dev_dir",
+    "core_dev_scripts_dir",
+    "personal_dir",
+    "personal_scripts_dir",
+    "personal_plugins_dir",
+    "personal_hooks_dir",
+    "personal_rules_dir",
+    "personal_skills_dir",
+    "brain_dir",
+    "personal_config_dir",
+    "personal_lib_dir",
+    "personal_overrides_dir",
+    "runtime_dir",
+    "data_dir",
+    "db_path",
+    "logs_dir",
+    "operations_dir",
+    "backups_dir",
+    "memory_dir",
+    "cognitive_dir",
+    "coordination_dir",
+    "exports_dir",
+    "nexo_email_dir",
+    "doctor_dir",
+    "snapshots_dir",
+    "crons_dir",
+    "all_scripts_dirs",
+    "all_plugins_dirs",
+    "all_hooks_dirs",
+    "all_rules_dirs",
+    "legacy_scripts_dir",
+    "legacy_brain_dir",
+    "legacy_data_dir",
+    "legacy_logs_dir",
+    "legacy_operations_dir",
+    "legacy_db_path",
+    "resolve_db_path",
+]

package/src/plugins/personal_plugins.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import os
+import paths
 from pathlib import Path
 
 from db import init_db
@@ -15,7 +16,7 @@ NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent
 
 
 def _plugins_dir() -> Path:
-    path = NEXO_HOME / "plugins"
+    path = paths.core_plugins_dir()
     path.mkdir(parents=True, exist_ok=True)
     return path
 

package/src/plugins/recover.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 import json
 import os
+import paths
 import re
 import sys
 import time
@@ -46,8 +47,8 @@ from db_guard import (
 )
 
 NEXO_HOME = export_resolved_nexo_home()
-DATA_DIR = NEXO_HOME / "data"
-BACKUP_BASE = NEXO_HOME / "backups"
+DATA_DIR = paths.data_dir()
+BACKUP_BASE = paths.backups_dir()
 PRIMARY_DB = DATA_DIR / "nexo.db"
 
 

package/src/plugins/update.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 """Update plugin — pull latest code, backup DBs, run migrations, verify."""
 import json
 import os
+import paths
 import re
 import shutil
 import sqlite3
@@ -84,8 +85,8 @@ CODE_ROOT = _THIS_DIR.parent
 _REPO_CANDIDATE = CODE_ROOT.parent
 
 NEXO_HOME = export_resolved_nexo_home()
-DATA_DIR = NEXO_HOME / "data"
-BACKUP_BASE = NEXO_HOME / "backups"
+DATA_DIR = paths.data_dir()
+BACKUP_BASE = paths.backups_dir()
 
 # In packaged installs, update.py lives at <NEXO_HOME>/plugins/update.py.
 _PACKAGED_INSTALL = not (_REPO_CANDIDATE / ".git").exists() and not (_REPO_CANDIDATE / ".git").is_file()
@@ -161,7 +162,7 @@ def _refresh_installed_manifest():
             return
 
         src_crons = artifact_src / "crons"
-        dst_crons = NEXO_HOME / "crons"
+        dst_crons = paths.crons_dir()
         if src_crons.exists():
             dst_crons.mkdir(parents=True, exist_ok=True)
             for f in src_crons.iterdir():
@@ -193,10 +194,10 @@ def _refresh_installed_manifest():
 def _cleanup_retired_runtime_files() -> list[str]:
     removed: list[str] = []
     retired_paths = [
-        NEXO_HOME / "scripts" / "heartbeat-enforcement.py",
-        NEXO_HOME / "scripts" / "heartbeat-posttool.sh",
-        NEXO_HOME / "scripts" / "heartbeat-user-msg.sh",
-        NEXO_HOME / "hooks" / "heartbeat-guard.sh",
+        paths.core_scripts_dir() / "heartbeat-enforcement.py",
+        paths.core_scripts_dir() / "heartbeat-posttool.sh",
+        paths.core_scripts_dir() / "heartbeat-user-msg.sh",
+        paths.core_hooks_dir() / "heartbeat-guard.sh",
     ]
     for path in retired_paths:
         if not path.exists():
@@ -723,7 +724,7 @@ def _sync_hooks_to_home():
     """Copy hook scripts from src/hooks/ to NEXO_HOME/hooks/ after update."""
     import shutil
     hooks_src = SRC_DIR / "hooks"
-    hooks_dest = NEXO_HOME / "hooks"
+    hooks_dest = paths.core_hooks_dir()
     if not hooks_src.is_dir():
         return
     hooks_dest.mkdir(parents=True, exist_ok=True)
@@ -893,7 +894,7 @@ def _paths_match(src: Path, dest: Path) -> bool:
 
 
 def _sync_packaged_crons(progress_fn=None) -> tuple[bool, str | None]:
-    sync_path = NEXO_HOME / "crons" / "sync.py"
+    sync_path = paths.crons_dir() / "sync.py"
     if not sync_path.is_file():
         _refresh_installed_manifest()
         return True, None

package/src/public_contribution.py

@@ -9,6 +9,7 @@ This module manages the opt-in "public core evolution" mode:
 
 import json
 import os
+import paths
 import platform
 import re
 import shutil
@@ -47,7 +48,7 @@ NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
 CONTRIB_ROOT = NEXO_HOME / "contrib" / "public-core"
 CONTRIB_REPO_DIR = CONTRIB_ROOT / "repo"
 CONTRIB_WORKTREES_DIR = CONTRIB_ROOT / "worktrees"
-CONTRIB_ARTIFACTS_DIR = NEXO_HOME / "operations" / "public-contrib"
+CONTRIB_ARTIFACTS_DIR = paths.operations_dir() / "public-contrib"
 
 
 def _utcnow() -> datetime:

package/src/runtime_power.py

@@ -15,6 +15,7 @@ Important semantic note:
 
 import json
 import os
+import paths
 import platform
 import plistlib
 import shutil
@@ -336,7 +337,7 @@ def detect_full_disk_access_reasons(*, system: str | None = None) -> list[str]:
             f"NEXO_HOME is inside a protected macOS folder: {NEXO_HOME}"
         )
 
-    logs_dir = NEXO_HOME / "logs"
+    logs_dir = paths.logs_dir()
     if logs_dir.is_dir():
         for log_file in sorted(logs_dir.glob("*-stderr.log")):
             if _tail_has_permission_denial(log_file):
@@ -715,7 +716,7 @@ def ensure_full_disk_access_choice(
 
 
 def _prevent_sleep_script_path() -> Path:
-    runtime_script = NEXO_HOME / "scripts" / "nexo-prevent-sleep.sh"
+    runtime_script = paths.core_scripts_dir() / "nexo-prevent-sleep.sh"
     if runtime_script.is_file():
         return runtime_script
     source_script = NEXO_CODE / "scripts" / "nexo-prevent-sleep.sh"
@@ -730,8 +731,8 @@ def _macos_prevent_sleep_plist() -> tuple[Path, dict]:
         "ProgramArguments": ["/bin/bash", str(script_path)],
         "RunAtLoad": True,
         "KeepAlive": True,
-        "StandardOutPath": str(NEXO_HOME / "logs" / "prevent-sleep-stdout.log"),
-        "StandardErrorPath": str(NEXO_HOME / "logs" / "prevent-sleep-stderr.log"),
+        "StandardOutPath": str(paths.logs_dir() / "prevent-sleep-stdout.log"),
+        "StandardErrorPath": str(paths.logs_dir() / "prevent-sleep-stderr.log"),
         "EnvironmentVariables": {
             "HOME": str(Path.home()),
             "NEXO_HOME": str(NEXO_HOME),
@@ -766,7 +767,7 @@ WantedBy=default.target
 def apply_power_policy(policy: str | None = None) -> dict:
     policy = normalize_power_policy(policy or get_power_policy())
     system = platform.system()
-    logs_dir = NEXO_HOME / "logs"
+    logs_dir = paths.logs_dir()
     logs_dir.mkdir(parents=True, exist_ok=True)
     details = describe_power_policy(policy=policy, system=system)