superlocalmemory 3.6.13 → 3.6.14

package/src/superlocalmemory/cli/commands.py

@@ -780,8 +780,97 @@ def _cmd_context_dispatch(args: Namespace) -> None:
     cmd_context(args)
 
 
+def _agents_md_source_factory():
+    """Return a callable that reads the WP-05 AGENTS.md content, or None on failure.
+
+    Source: plugin-src/rules/AGENTS.md (relative to package root).
+    Gracefully skips if absent — never fails the MCP write.
+    """
+    from pathlib import Path
+
+    # Resolve relative to the package root (src/superlocalmemory/../../)
+    _pkg_root = Path(__file__).resolve().parents[3]
+    _agents_src = _pkg_root / "plugin-src" / "rules" / "AGENTS.md"
+
+    def _read() -> str | None:
+        if _agents_src.exists():
+            return _agents_src.read_text(encoding="utf-8")
+        logger.warning(
+            "WP-05 AGENTS.md not found at %s — skipping AGENTS.md write", _agents_src
+        )
+        return None
+
+    return _read
+
+
 def cmd_connect(args: Namespace) -> None:
-    """Configure IDE integrations. V3.4.22: ``--cross-platform`` uses LLD-05."""
+    """Configure IDE integrations.
+
+    Dispatch priority (WP-08):
+    1. ``slm connect <ide>`` where ide ∈ IDE_MATRIX → portable_kit.connect_ide
+       (MCP-wiring + AGENTS.md; includes claude-code short-circuit to WP-06).
+    2. ``--cross-platform`` / ``--disable`` → LLD-05 CrossPlatformConnector.
+    3. Bare ``slm connect`` / ``--list`` → legacy IDEConnector (markdown-rules).
+    """
+    ide_arg = getattr(args, "ide", None)
+
+    # WP-08: intercept known IDE_MATRIX ids before legacy branches (CRIT-1)
+    if ide_arg is not None:
+        from superlocalmemory.hooks.portable_kit import (
+            IDE_MATRIX,
+            connect_ide,
+            supported_ides,
+        )
+
+        if ide_arg in IDE_MATRIX:
+            here = getattr(args, "here", False)
+            profile = getattr(args, "profile", None)
+            project = None
+            if here:
+                import pathlib
+                project = pathlib.Path.cwd()
+
+            result = connect_ide(
+                ide_arg,
+                home=None,
+                project=project,
+                here=here,
+                profile=profile,
+                agents_md_source=_agents_md_source_factory(),
+            )
+
+            if getattr(args, "json", False):
+                from superlocalmemory.cli.json_output import json_print
+                json_print("connect", data=result)
+                return
+
+            if result["error"]:
+                print(f"Error: {result['error']}", file=sys.stderr)
+                print(
+                    f"Supported IDEs: {', '.join(supported_ides())}",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+            status_sym = {"wrote": "[+]", "merged": "[~]", "unchanged": "[=]",
+                          "skipped": "[s]", "error": "[!]"}.get(
+                result["mcp_config"], "[?]"
+            )
+            print(
+                f"{status_sym} {ide_arg}: mcp_config={result['mcp_config']} "
+                f"path={result['mcp_path']}"
+            )
+            print(f"    agents_md={result['agents_md']}")
+            return
+
+        # Unknown ide — list supported and exit non-zero
+        from superlocalmemory.hooks.portable_kit import supported_ides
+        print(
+            f"Unknown IDE '{ide_arg}'.\nSupported: {', '.join(supported_ides())}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
     # Route --disable <name> and --cross-platform to the LLD-05 orchestrator.
     if getattr(args, "disable", None) or getattr(args, "cross_platform", False):
         from superlocalmemory.cli.context_commands import (
@@ -1318,14 +1407,60 @@ def cmd_status(args: Namespace) -> None:
 
     if getattr(args, 'json', False):
         from superlocalmemory.cli.json_output import json_print
+
+        # WP-02 D8: canonical key set — db_size_mb always present (0.0 if absent).
+        db_size_mb = 0.0
+        if config.db_path.exists():
+            db_size_mb = round(config.db_path.stat().st_size / 1024 / 1024, 2)
+
+        # Open engine for counts (json branch only — LLD Decision B).
+        # Fail-open to 0 on any error; status must never crash.
+        # Guard on db existence: `slm status --json` must stay observational —
+        # opening the engine on a fresh install would create + migrate the db
+        # (MemoryEngine.initialize → DatabaseManager mkdir/connect/DDL). A
+        # previously read-only command must not acquire a write side-effect.
+        fact_count = 0
+        entity_count = 0
+        edge_count = 0
+        eng = None
+        if config.db_path.exists():
+            try:
+                from superlocalmemory.core.engine import MemoryEngine
+                from superlocalmemory.core.engine_capabilities import Capabilities
+                eng = MemoryEngine(config, capabilities=Capabilities.LIGHT)
+                eng.initialize()
+                pid = config.active_profile
+                fact_count = eng._db.get_fact_count(pid)
+                rows = eng._db.execute(
+                    "SELECT COUNT(*) AS c FROM canonical_entities WHERE profile_id = ?",
+                    (pid,),
+                )
+                entity_count = int(dict(rows[0])["c"]) if rows else 0
+                rows2 = eng._db.execute(
+                    "SELECT COUNT(*) AS c FROM graph_edges WHERE profile_id = ?",
+                    (pid,),
+                )
+                edge_count = int(dict(rows2[0])["c"]) if rows2 else 0
+            except Exception:
+                logger.debug("cmd_status: engine count query failed; using 0s", exc_info=True)
+            finally:
+                if eng is not None:
+                    try:
+                        eng.close()
+                    except Exception:
+                        pass
+
         data = {
             "mode": config.mode.value.upper(),
             "provider": config.llm.provider or "none",
+            "profile": config.active_profile,
             "base_dir": str(config.base_dir),
             "db_path": str(config.db_path),
+            "db_size_mb": db_size_mb,
+            "fact_count": fact_count,
+            "entity_count": entity_count,
+            "edge_count": edge_count,
         }
-        if config.db_path.exists():
-            data["db_size_mb"] = round(config.db_path.stat().st_size / 1024 / 1024, 2)
         json_print("status", data=data, next_actions=[
             {"command": "slm health --json", "description": "Check math layer health"},
             {"command": "slm list --json", "description": "List recent memories"},
@@ -1406,6 +1541,63 @@ def cmd_health(args: Namespace) -> None:
     print(f"  Mode: {config.mode.value.upper()}")
 
 
+def _gather_optimize_surface_b() -> dict:
+    """Gather Surface-B health data for slm doctor.
+
+    Pure data-gather — never raises, never prints, never starts the
+    ConfigStore watchdog thread. Reads daemon-persisted metrics only
+    (CacheDB.metrics_load), never the in-process KV counters.
+
+    Returns a dict with keys:
+        enabled, cache_enabled, compress_enabled, proxy_enabled,
+        compress_runs, tokens_saved, cache_hits, cache_misses,
+        db_present, error
+    """
+    from pathlib import Path
+    from superlocalmemory.optimize.storage.db import CacheDB
+
+    result: dict = {
+        "enabled": False,
+        "cache_enabled": False,
+        "compress_enabled": False,
+        "proxy_enabled": False,
+        "compress_runs": 0,
+        "tokens_saved": 0,
+        "cache_hits": 0,
+        "cache_misses": 0,
+        "db_present": False,
+        "error": "",
+    }
+
+    # Step 1: read optimize config — NO watchdog start.
+    try:
+        from superlocalmemory.optimize.config.store import ConfigStore
+        cfg = ConfigStore().get()
+        result["enabled"] = cfg.enabled
+        result["cache_enabled"] = cfg.cache_enabled
+        result["compress_enabled"] = cfg.compress_enabled
+        result["proxy_enabled"] = cfg.proxy_enabled
+    except Exception as exc:  # noqa: BLE001
+        result["error"] = str(exc)
+        # enabled stays False — safe default
+
+    # Step 2: read persisted metrics from llmcache.db (daemon-flushed, ≤60s stale).
+    try:
+        db_path = Path.home() / ".superlocalmemory" / "llmcache.db"
+        result["db_present"] = db_path.exists()
+        if result["db_present"]:
+            snap = CacheDB.get_default().metrics_load()
+            result["compress_runs"] = snap.compress_runs
+            result["tokens_saved"] = snap.tokens_saved_compress
+            result["cache_hits"] = snap.hits
+            result["cache_misses"] = snap.misses
+    except Exception as exc:  # noqa: BLE001
+        prior = result["error"]
+        result["error"] = (prior + "; " if prior else "") + "metrics read failed"
+
+    return result
+
+
 def cmd_doctor(args: Namespace) -> None:
     """Comprehensive pre-flight check — verify everything works.
 
@@ -1680,6 +1872,89 @@ def cmd_doctor(args: Namespace) -> None:
     else:
         _check("Database", "PASS", "not yet created (will initialize on first use)")
 
+    # 11. PEP 668 advisory — WP-07: detect EXTERNALLY-MANAGED marker and
+    #     recommend pipx when the system Python is managed by the OS package
+    #     manager (e.g. Homebrew, Debian/Ubuntu, Fedora 38+).
+    try:
+        import sysconfig as _sc
+        _stdlib = _sc.get_path("stdlib")
+        if _stdlib:
+            _em_marker = Path(_stdlib) / "EXTERNALLY-MANAGED"
+            if _em_marker.exists():
+                _check(
+                    "PEP 668 / Install method",
+                    "WARN",
+                    "System Python is externally managed (EXTERNALLY-MANAGED marker found). "
+                    "pip install may fail with PEP 668 error.",
+                    "Use pipx for an isolated install: pipx install superlocalmemory  "
+                    "(last-resort only: pip install --break-system-packages superlocalmemory)",
+                )
+            else:
+                _check(
+                    "PEP 668 / Install method",
+                    "PASS",
+                    "No EXTERNALLY-MANAGED marker — standard pip install supported",
+                )
+    except Exception:
+        pass  # advisory only — never fail doctor on this check
+
+    # 12. Optimize (Surface B) — reads daemon-persisted metrics (≤60s stale).
+    info = _gather_optimize_surface_b()
+    _enabled = info["enabled"]
+    _error = info.get("error", "")
+    if not _enabled:
+        _check(
+            "Optimize (Surface B)",
+            "WARN",
+            "disabled (optimize.json enabled=false) — caching/compression not active"
+            + (f" [{_error}]" if _error else ""),
+            fix="Enable via dashboard Optimize tab or set enabled=true"
+            " in ~/.superlocalmemory/optimize.json",
+        )
+    else:
+        _surfaces = []
+        if info["cache_enabled"]:
+            _surfaces.append("cache")
+        if info["compress_enabled"]:
+            _surfaces.append("compress")
+        if info["proxy_enabled"]:
+            _surfaces.append("proxy")
+        _stats = (
+            f"compress_runs={info['compress_runs']}"
+            f" tokens_saved={info['tokens_saved']}"
+            f" cache_hits={info['cache_hits']}"
+            f" cache_misses={info['cache_misses']}"
+        )
+        _surface_str = ",".join(_surfaces) if _surfaces else "(none)"
+        if not _surfaces:
+            _check(
+                "Optimize (Surface B)",
+                "WARN",
+                f"enabled [{_surface_str}] but no surface active"
+                + (f" [{_error}]" if _error else ""),
+            )
+        elif not info["db_present"]:
+            _check(
+                "Optimize (Surface B)",
+                "WARN",
+                f"enabled [{_surface_str}] {_stats}"
+                " but no metrics yet (llmcache.db not created)"
+                + (f" [{_error}]" if _error else ""),
+                fix="slm serve start",
+            )
+        elif _error:
+            _check(
+                "Optimize (Surface B)",
+                "WARN",
+                f"enabled [{_surface_str}] {_stats} (partial: {_error})",
+            )
+        else:
+            _check(
+                "Optimize (Surface B)",
+                "PASS",
+                f"enabled [{_surface_str}] {_stats}",
+            )
+
     # Summary
     if use_json:
         from superlocalmemory.cli.json_output import json_print
@@ -2003,14 +2278,82 @@ def cmd_profile(args: Namespace) -> None:
 # -- Active Memory commands (V3.1) ------------------------------------------
 
 
+def _cmd_init_auto(
+    args: Namespace,
+    slm_data_dir: "Path",
+    config_exists: bool,
+    force: bool,
+) -> None:
+    """WP-07: non-interactive --auto branch for slm init.
+
+    Best-effort at every step; only exits non-zero when config save fails.
+    No TTY required.  Does NOT run IDE connect (AC6).
+    """
+    from pathlib import Path
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.storage.models import Mode
+    from superlocalmemory.cli.setup_wizard import _mark_complete
+
+    # Step 1: write mode-A config (create-if-absent or --force).
+    # Pass slm_data_dir explicitly so env-overridden paths are respected even
+    # when DEFAULT_BASE_DIR was evaluated before the env var was set (e.g. tests).
+    if force or not config_exists:
+        try:
+            cfg = SLMConfig.for_mode(Mode.A, base_dir=slm_data_dir)
+            cfg.save(mode_change=True)
+        except Exception as exc:
+            print(f"[ERROR] slm init --auto: config save failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    # Step 2: mark complete (write .setup-complete sentinel).
+    # Write the sentinel directly using slm_data_dir to avoid the module-level
+    # _SLM_HOME resolved at import time (tests set the env var after import).
+    try:
+        import platform
+        import time as _time
+        sentinel = slm_data_dir / ".setup-complete"
+        slm_data_dir.mkdir(parents=True, exist_ok=True)
+        sentinel.write_text(
+            f"setup_completed={_time.strftime('%Y-%m-%dT%H:%M:%S')}\n"
+            f"python={sys.executable}\n"
+            f"platform={platform.system()}\n"
+            f"version={platform.python_version()}\n"
+        )
+    except Exception:
+        pass  # best-effort — sentinel is advisory only
+
+    # Step 3: install hooks if ~/.claude exists.
+    try:
+        claude_dir = Path.home() / ".claude"
+        if claude_dir.exists():
+            from superlocalmemory.hooks.claude_code_hooks import install_hooks
+            install_hooks(include_gate=getattr(args, "gate", False))
+    except Exception:
+        pass  # best-effort
+
+    # Step 4: warmup best-effort (don't block if models not present).
+    # Skipped in --auto to keep startup fast for CI; user can run slm warmup.
+
+    print("[OK] slm init --auto: setup complete (mode A, non-interactive)", file=sys.stderr)
+
+
 def cmd_init(args: Namespace) -> None:
     """One-command setup: mode + hooks + IDE connect + warmup."""
     from pathlib import Path
+    from superlocalmemory.cli._lazy_init import slm_home
     from superlocalmemory.core.config import SLMConfig
 
     force = getattr(args, "force", False)
+    auto = getattr(args, "auto", False)
+
+    slm_data_dir = slm_home()
+    config_exists = (slm_data_dir / "config.json").exists()
 
-    config_exists = (Path.home() / ".superlocalmemory" / "config.json").exists()
+    # WP-07: --auto branch — fully non-interactive, no TTY required (AC6).
+    if auto:
+        os.environ["SLM_NON_INTERACTIVE"] = "1"
+        _cmd_init_auto(args, slm_data_dir, config_exists, force)
+        return
 
     print()
     print("SuperLocalMemory — One-Time Setup")
@@ -2114,41 +2457,7 @@ def cmd_hooks(args: Namespace) -> None:
             if include_gate:
                 print("  Gate: ON (enforces session_init — experimental)")
             print("  SLM: Hooks installed into Claude Code (slm hooks remove to undo)")
-            # S9-DASH-11: also install skills so /slm-recall, /slm-remember
-            # etc. are available immediately in Claude Code regardless of
-            # whether the user installed via npm or pip.
-            try:
-                import importlib.resources as _ir
-                import importlib.util as _iu
-                import shutil as _sh
-                from pathlib import Path as _P
-
-                claude_skills_dir = _P.home() / ".claude" / "skills"
-                claude_skills_dir.mkdir(parents=True, exist_ok=True)
-
-                # Try Python-package bundled skills first (works for both
-                # pip and npm users who have the Python pkg installed).
-                pkg_skills: _P | None = None
-                spec = _iu.find_spec("superlocalmemory")
-                if spec and spec.submodule_search_locations:
-                    candidate = _P(list(spec.submodule_search_locations)[0]) / "skills"
-                    if candidate.is_dir():
-                        pkg_skills = candidate
-
-                if pkg_skills:
-                    installed_skills = 0
-                    for d in pkg_skills.iterdir():
-                        if d.is_dir():
-                            src_skill = d / "SKILL.md"
-                            if src_skill.exists():
-                                dst = claude_skills_dir / (d.name + ".md")
-                                _sh.copy2(str(src_skill), str(dst))
-                                installed_skills += 1
-                    if installed_skills:
-                        print(f"  Skills: {installed_skills} skills installed → {claude_skills_dir}")
-                        print("           Use /slm-recall, /slm-remember, /slm-status in Claude Code")
-            except Exception as _skill_exc:
-                pass  # non-fatal — skills can be installed via install-skills.sh
+
         else:
             print(f"Installation failed: {result['errors']}")
     elif action == "remove":

package/src/superlocalmemory/cli/main.py

@@ -24,6 +24,8 @@ _os.environ.setdefault('TORCH_DEVICE', 'cpu')
 import argparse
 import sys
 
+from superlocalmemory.core.config import CANONICAL_RECALL_LIMIT
+
 _HELP_EPILOG = """\
 operating modes:
   Mode A  Local Guardian — Zero cloud, zero LLM. All processing stays on
@@ -76,6 +78,17 @@ def main() -> None:
         handle_hook(sys.argv[2])
         return
 
+    # WP-07: lazy first-run init — runs after hook/mcp fast-paths so stdout
+    # is never polluted on those paths (CRIT-3, MCP JSON-RPC purity).
+    # Guarded: any failure must not crash the CLI (AC4).
+    _is_mcp_cmd = len(sys.argv) >= 2 and sys.argv[1] == "mcp"
+    if not _is_mcp_cmd:
+        try:
+            from superlocalmemory.cli._lazy_init import _ensure_initialized
+            _ensure_initialized()
+        except Exception:
+            pass
+
     from superlocalmemory.cli.json_output import _get_version
     _ver = _get_version()
 
@@ -101,8 +114,9 @@ def main() -> None:
                 from superlocalmemory.migrations.v3_4_25_to_v3_4_26 import (
                     migrate_if_safe as _migrate_if_safe,
                 )
-                _data = _P(_os.environ.get("SLM_DATA_DIR")
-                           or _P.home() / ".superlocalmemory")
+                # WP-07: route through slm_home() so all 3 env aliases are honoured.
+                from superlocalmemory.cli._lazy_init import slm_home as _slm_home
+                _data = _slm_home()
                 _res = _migrate_if_safe(_data)
                 if _res.get("status") == "deferred":
                     print(
@@ -140,6 +154,11 @@ def main() -> None:
         "--gate", action="store_true",
         help="Enable PreToolUse gate (experimental — blocks tools until session_init)",
     )
+    # WP-07: non-interactive auto setup (pip post-install, CI, scripts).
+    init_p.add_argument(
+        "--auto", action="store_true",
+        help="Non-interactive setup: mode A + hooks (no TTY required, for CI/scripts)",
+    )
 
     setup_p = sub.add_parser("setup", help="Interactive first-time setup wizard")
     setup_p.add_argument(
@@ -159,11 +178,32 @@ def main() -> None:
     )
 
     connect_p = sub.add_parser("connect", help="Auto-configure IDE integrations (17+ IDEs)")
-    connect_p.add_argument("ide", nargs="?", help="Specific IDE to configure")
+    connect_p.add_argument("ide", nargs="?", help="Specific IDE to configure (e.g. cursor, codex, continue)")
     connect_p.add_argument(
         "--list", action="store_true", help="List all supported IDEs",
     )
     connect_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
+    # WP-08 CRIT-1: declare missing flags so cmd_connect can read them without getattr fallback
+    connect_p.add_argument(
+        "--here", action="store_true", default=False,
+        help="Write config relative to current working directory (project scope)",
+    )
+    connect_p.add_argument(
+        "--cross-platform", action="store_true", dest="cross_platform", default=False,
+        help="Use LLD-05 cross-platform adapter orchestrator",
+    )
+    connect_p.add_argument(
+        "--disable", metavar="ADAPTER", default=None,
+        help="Disable a specific cross-platform adapter by name",
+    )
+    connect_p.add_argument(
+        "--profile", metavar="PROFILE", default=None,
+        help="Inject SLM_MCP_PROFILE env var into the MCP server block (WP-01)",
+    )
+    connect_p.add_argument(
+        "--dry-run", action="store_true", dest="dry_run", default=False,
+        help="Show what would be written without making changes",
+    )
 
     migrate_p = sub.add_parser("migrate", help="Migrate data from V2 to V3 schema")
     migrate_p.add_argument(
@@ -200,7 +240,10 @@ def main() -> None:
     # same search verb the MCP exposes (handlers dict maps both to cmd_recall).
     recall_p = sub.add_parser("recall", aliases=["search"], help="Semantic search with 4-channel retrieval")
     recall_p.add_argument("query", help="Search query")
-    recall_p.add_argument("--limit", type=int, default=10, help="Max results (default 10)")
+    recall_p.add_argument(
+        "--limit", type=int, default=CANONICAL_RECALL_LIMIT,
+        help=f"Max results (default {CANONICAL_RECALL_LIMIT})",
+    )
     recall_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
     recall_p.add_argument(
         "--fast", action="store_true",

package/src/superlocalmemory/cli/setup_wizard.py

@@ -28,7 +28,17 @@ from pathlib import Path
 # Constants
 # ---------------------------------------------------------------------------
 
-_SLM_HOME = Path(os.environ.get("SL_MEMORY_PATH", Path.home() / ".superlocalmemory"))
+# WP-07: resolve via slm_home() so all 3 env aliases are honoured.
+# Fallback keeps stdlib-only path if the import fails during early bootstrap.
+def _resolve_slm_home() -> Path:
+    try:
+        from superlocalmemory.cli._lazy_init import slm_home
+        return slm_home()
+    except Exception:
+        return Path(os.environ.get("SL_MEMORY_PATH", "") or Path.home() / ".superlocalmemory")
+
+
+_SLM_HOME = _resolve_slm_home()
 _SETUP_MARKER = _SLM_HOME / ".setup-complete"
 _EMBED_MODEL = "nomic-ai/nomic-embed-text-v1.5"
 _RERANKER_MODEL = "cross-encoder/ms-marco-MiniLM-L-12-v2"
@@ -703,14 +713,18 @@ def check_first_use(command: str) -> None:
     if is_setup_complete():
         return
 
-    # Non-interactive: use defaults silently, don't block the command
+    # Non-interactive: use defaults silently, don't block the command.
+    # CRIT-1: only save config when it does NOT already exist — lazy-init may
+    # have already written a valid config.json; overwriting it here would clobber
+    # any lazy-init content (e.g. a pre-existing mode-A skeleton).
     if not is_interactive():
-        # Just create config with defaults and mark complete
         try:
-            from superlocalmemory.core.config import SLMConfig
+            from superlocalmemory.core.config import SLMConfig, DEFAULT_BASE_DIR
             from superlocalmemory.storage.models import Mode
-            config = SLMConfig.for_mode(Mode.A)
-            config.save(mode_change=True)
+            config_path = DEFAULT_BASE_DIR / "config.json"
+            if not config_path.exists():
+                cfg = SLMConfig.for_mode(Mode.A)
+                cfg.save(mode_change=True)
             _mark_complete()
         except Exception:
             pass