superlocalmemory 3.6.13 → 3.6.15

package/src/superlocalmemory/cli/commands.py

@@ -94,6 +94,48 @@ def _cmd_help_optimize(args: Namespace) -> None:
 # ---- end SLM v3.6 Optimize dispatch functions ----
 
 
+def cmd_session(args: Namespace) -> None:
+    """#49: Open/close a session locally via the daemon — no model roundtrip,
+    so a shell hook (e.g. Claude session-start / /quit) can call it directly.
+    """
+    from superlocalmemory.cli.daemon import (
+        daemon_request, ensure_daemon, is_daemon_running,
+    )
+
+    action = getattr(args, "session_command", None)
+    if action not in ("open", "close"):
+        print("Usage: slm session {open|close} "
+              "[--session-id ID] [--project-path PATH] [--query Q]")
+        return
+
+    if not is_daemon_running():
+        ensure_daemon()
+
+    if action == "open":
+        body = {
+            "project_path": getattr(args, "project_path", "") or "",
+            "query": getattr(args, "query", "") or "",
+            "max_results": int(getattr(args, "max_results", 10) or 10),
+        }
+        resp = daemon_request("POST", "/session/open", body)
+        if resp and resp.get("ok"):
+            print(f"Session opened — warmed {resp.get('warmed', 0)} memories "
+                  f"(query: {resp.get('query', '')})")
+        else:
+            print("Session open failed (daemon unreachable?)")
+        return
+
+    # close
+    body = {"session_id": getattr(args, "session_id", "") or ""}
+    resp = daemon_request("POST", "/session/close", body)
+    if resp and resp.get("ok"):
+        sid = resp.get("session_id") or "(most recent)"
+        print(f"Session closed: {sid} — "
+              f"{resp.get('summary_events_created', 0)} summary event(s) created")
+    else:
+        print("Session close failed (daemon unreachable?)")
+
+
 def dispatch(args: Namespace) -> None:
     """Route CLI command to the appropriate handler."""
     # Auto-install/upgrade hooks on version change (single file read, ~0.1ms)
@@ -128,6 +170,7 @@ def dispatch(args: Namespace) -> None:
         "profile": cmd_profile,
         "hooks": cmd_hooks,
         "session-context": cmd_session_context,
+        "session": cmd_session,  # #49: local session open/close for hooks
         "observe": cmd_observe,
         # V3.3 commands
         "decay": cmd_decay,
@@ -780,8 +823,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 (
@@ -904,6 +1036,19 @@ def cmd_remember(args: Namespace) -> None:
 
     use_json = getattr(args, 'json', False)
     sync_mode = getattr(args, 'sync_mode', False)
+    # v3.6.15 multi-scope: scope=None means "not specified" → resolve to the
+    # configured default_scope (personal) at the daemon / engine boundary.
+    # Shared memory is opt-in, so an unset --scope always stays private.
+    scope = getattr(args, 'scope', None)
+    # v3.6.15: --shared-with is a comma-separated string on the CLI, but the
+    # daemon (RememberRequest) and engine expect list[str]. Parse here so an
+    # explicit `--shared-with a,b` doesn't 422 at the daemon and silently fall
+    # back to a personal write.
+    _sw_raw = getattr(args, 'shared_with', None)
+    shared_with = (
+        [s.strip() for s in _sw_raw.split(",") if s.strip()]
+        if isinstance(_sw_raw, str) and _sw_raw.strip() else _sw_raw
+    )
 
     # V3.3.21: Route through daemon for instant remember (no cold start).
     # If daemon is running, send request directly (~0.1s).
@@ -916,6 +1061,8 @@ def cmd_remember(args: Namespace) -> None:
                 result = daemon_request("POST", "/remember", {
                     "content": args.content,
                     "tags": args.tags or "",
+                    "scope": scope,
+                    "shared_with": shared_with,
                 })
                 if result and "fact_ids" in result:
                     if use_json:
@@ -931,9 +1078,20 @@ def cmd_remember(args: Namespace) -> None:
         # NO subprocess spawn. Daemon's background loop picks up pending memories.
         from superlocalmemory.cli.pending_store import store_pending
 
+        # v3.6.15 multi-scope: carry an explicit non-personal scope into the
+        # pending row's metadata so the materializer replays the right
+        # visibility. Unset / personal carries nothing — byte-identical to
+        # pre-3.6.15 pending rows.
+        _pending_meta = None
+        if scope and scope != "personal":
+            _pending_meta = {"scope": scope}
+            if shared_with:
+                _pending_meta["shared_with"] = shared_with
+
         row_id = store_pending(
             content=args.content,
             tags=args.tags or "",
+            metadata=_pending_meta,
         )
 
         if use_json:
@@ -951,8 +1109,13 @@ def cmd_remember(args: Namespace) -> None:
         engine = MemoryEngine(config)
         engine.initialize()
 
+        # v3.6.15: resolve an unset scope to the configured default_scope.
+        _scope = scope or getattr(getattr(config, "scope", None), "default_scope", "personal")
         metadata = {"tags": args.tags} if args.tags else {}
-        fact_ids = engine.store(args.content, metadata=metadata)
+        fact_ids = engine.store(
+            args.content, metadata=metadata,
+            scope=_scope, shared_with=shared_with,
+        )
     except Exception as exc:
         if use_json:
             from superlocalmemory.cli.json_output import json_print
@@ -975,6 +1138,11 @@ def cmd_remember(args: Namespace) -> None:
 def cmd_recall(args: Namespace) -> None:
     """Search memories via the engine — routes through daemon if available."""
     use_json = getattr(args, 'json', False)
+    # v3.6.15: None = "not specified" → daemon/engine resolves the configured
+    # default (shared-off). Only an explicit --include-global / --no-global
+    # produces True/False here.
+    include_global = getattr(args, 'include_global', None)
+    include_shared = getattr(args, 'include_shared', None)
 
     # V3.3.21: Route through daemon for instant response (no cold start).
     # Falls back to direct engine if daemon not running.
@@ -988,10 +1156,18 @@ def cmd_recall(args: Namespace) -> None:
             from urllib.parse import quote
             session_id = f"cli:{os.getppid()}"
             fast_qs = "&fast=true" if getattr(args, "fast", False) else ""
+            # Only send scope flags when the user set them explicitly; absent =
+            # let the daemon resolve the configured default. (Never emit
+            # "none" — that would parse as a missing/false value.)
+            scope_qs = ""
+            if include_global is not None:
+                scope_qs += f"&include_global={str(include_global).lower()}"
+            if include_shared is not None:
+                scope_qs += f"&include_shared={str(include_shared).lower()}"
             result = daemon_request(
                 "GET",
                 f"/recall?q={quote(args.query)}&limit={args.limit}"
-                f"&session_id={quote(session_id)}{fast_qs}",
+                f"&session_id={quote(session_id)}{fast_qs}{scope_qs}",
             )
             if result and "results" in result:
                 # Format daemon response same as engine response
@@ -1025,6 +1201,8 @@ def cmd_recall(args: Namespace) -> None:
         response = engine.recall(
             args.query, limit=args.limit,
             fast=getattr(args, "fast", False),
+            include_global=include_global,
+            include_shared=include_shared,
         )
     except Exception as exc:
         if use_json:
@@ -1318,14 +1496,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 +1630,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 +1961,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 +2367,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 +2546,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":