superlocalmemory 3.4.19 → 3.4.22

package/src/superlocalmemory/hooks/context_payload.py

@@ -0,0 +1,312 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.22 — LLD-05 §3
+
+"""Shared content builder — single source for every adapter body.
+
+LLD reference: ``.backup/active-brain/lld/LLD-05-cross-platform-adapters.md``
+Section 3 (Content Builder). One builder → five formatters. Every string is
+passed through ``redact_secrets`` before entering the dataclass, so no
+adapter ever writes an unredacted secret.
+
+Hard rule A9: secret redaction applied to payload before write.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Iterable
+
+from superlocalmemory.core.security_primitives import redact_secrets
+
+
+VERSION = "3.4.22"
+DEFAULT_TOP_K = 10
+DEFAULT_DECISIONS_K = 5
+DEFAULT_MEMORIES_K = 10
+
+# A RecallFn takes (query, limit, profile_id) and returns a list of memory
+# dicts with at least {"text": str, "score": float}. Adapters inject the
+# real recall engine at construction time; tests inject a fake.
+RecallFn = Callable[[str, int, str], list[dict]]
+
+
+@dataclass(frozen=True, slots=True)
+class ContextPayload:
+    """Normalised, redacted context ready for any adapter to format.
+
+    All strings are post-redaction. Topics and entities are ranked tuples to
+    keep the structure immutable and deterministically serialisable.
+    """
+
+    profile_id: str
+    topics: tuple[tuple[str, float], ...]
+    entities: tuple[tuple[str, int], ...]
+    recent_decisions: tuple[str, ...]
+    project_memories: tuple[str, ...]
+    generated_at: str
+    version: str = VERSION
+
+
+# ---------------------------------------------------------------------------
+# Builder
+# ---------------------------------------------------------------------------
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _redact_str(s: str) -> str:
+    return redact_secrets(s) if isinstance(s, str) else ""
+
+
+def _redact_seq(items: Iterable[str], limit: int) -> tuple[str, ...]:
+    cleaned: list[str] = []
+    for item in items:
+        if not isinstance(item, str) or not item:
+            continue
+        cleaned.append(_redact_str(item))
+        if len(cleaned) >= limit:
+            break
+    return tuple(cleaned)
+
+
+def _recall_topics(
+    recall_fn: RecallFn, profile_id: str, scope: str, limit: int,
+) -> tuple[tuple[str, float], ...]:
+    query = "topics" if scope == "global" else "project topics"
+    try:
+        results = recall_fn(query, limit, profile_id) or []
+    except Exception:
+        return ()
+    topics: list[tuple[str, float]] = []
+    for row in results:
+        if not isinstance(row, dict):
+            continue
+        name = row.get("name") or row.get("text") or ""
+        if not isinstance(name, str) or not name:
+            continue
+        strength = float(row.get("score", row.get("strength", 0.0)) or 0.0)
+        topics.append((_redact_str(name), strength))
+        if len(topics) >= limit:
+            break
+    return tuple(topics)
+
+
+def _recall_entities(
+    recall_fn: RecallFn, profile_id: str, scope: str, limit: int,
+) -> tuple[tuple[str, int], ...]:
+    query = "entities" if scope == "global" else "project entities"
+    try:
+        results = recall_fn(query, limit, profile_id) or []
+    except Exception:
+        return ()
+    entities: list[tuple[str, int]] = []
+    for row in results:
+        if not isinstance(row, dict):
+            continue
+        name = row.get("name") or row.get("text") or ""
+        if not isinstance(name, str) or not name:
+            continue
+        mentions = int(row.get("mentions", row.get("count", 0)) or 0)
+        entities.append((_redact_str(name), mentions))
+        if len(entities) >= limit:
+            break
+    return tuple(entities)
+
+
+def _recall_decisions(
+    recall_fn: RecallFn, profile_id: str, limit: int,
+) -> tuple[str, ...]:
+    try:
+        rows = recall_fn("recent decisions", limit, profile_id) or []
+    except Exception:
+        return ()
+    texts = (row.get("text", "") for row in rows if isinstance(row, dict))
+    return _redact_seq(texts, limit)
+
+
+def _recall_memories(
+    recall_fn: RecallFn, profile_id: str, scope: str, limit: int,
+) -> tuple[str, ...]:
+    query = "project memories" if scope == "project" else "memories"
+    try:
+        rows = recall_fn(query, limit, profile_id) or []
+    except Exception:
+        return ()
+    texts = (row.get("text", "") for row in rows if isinstance(row, dict))
+    return _redact_seq(texts, limit)
+
+
+def build_payload(
+    profile_id: str,
+    scope: str,
+    cwd: Path,
+    *,
+    recall_fn: RecallFn,
+    top_k: int = DEFAULT_TOP_K,
+    decisions_k: int = DEFAULT_DECISIONS_K,
+    memories_k: int = DEFAULT_MEMORIES_K,
+    now_fn: Callable[[], str] | None = None,
+) -> ContextPayload:
+    """Build a redacted, ranked context payload.
+
+    ``scope`` ∈ {"project", "global"}. ``cwd`` is informational for the
+    recall engine (engine-specific signals can key off it); the builder
+    itself is a pure transform. ``recall_fn`` is injected — adapters wire
+    it to the real engine, tests wire a fake.
+    """
+    if scope not in ("project", "global"):
+        raise ValueError(f"scope must be 'project' or 'global', got {scope!r}")
+
+    topics = _recall_topics(recall_fn, profile_id, scope, top_k)
+    entities = _recall_entities(recall_fn, profile_id, scope, top_k)
+    decisions = _recall_decisions(recall_fn, profile_id, decisions_k)
+    memories = _recall_memories(recall_fn, profile_id, scope, memories_k)
+
+    # Late-bind ``now_fn`` so monkeypatching ``_now_iso`` at module scope
+    # still controls the timestamp — crucial for deterministic content-hash
+    # tests across sync attempts.
+    ts_fn = now_fn if now_fn is not None else _now_iso
+
+    return ContextPayload(
+        profile_id=profile_id,
+        topics=topics,
+        entities=entities,
+        recent_decisions=decisions,
+        project_memories=memories,
+        generated_at=ts_fn(),
+        version=VERSION,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Formatting helpers
+# ---------------------------------------------------------------------------
+
+
+def format_topics(payload: ContextPayload, limit: int = DEFAULT_TOP_K) -> str:
+    if not payload.topics:
+        return "_(none yet)_"
+    lines = []
+    for name, strength in payload.topics[:limit]:
+        lines.append(f"- {name} ({strength:.2f})")
+    return "\n".join(lines)
+
+
+def format_entities(
+    payload: ContextPayload, limit: int = DEFAULT_TOP_K,
+) -> str:
+    if not payload.entities:
+        return "_(none yet)_"
+    lines = []
+    for name, mentions in payload.entities[:limit]:
+        lines.append(f"- {name} ({mentions})")
+    return "\n".join(lines)
+
+
+def format_decisions(
+    payload: ContextPayload, limit: int = DEFAULT_DECISIONS_K,
+) -> str:
+    if not payload.recent_decisions:
+        return "_(none yet)_"
+    return "\n".join(f"- {d}" for d in payload.recent_decisions[:limit])
+
+
+def format_memories(
+    payload: ContextPayload, limit: int = DEFAULT_MEMORIES_K,
+) -> str:
+    if not payload.project_memories:
+        return "_(none yet)_"
+    return "\n".join(f"- {m}" for m in payload.project_memories[:limit])
+
+
+def truncate_payload_for_cap(
+    payload: ContextPayload, *, hard_cap: int, render: Callable[[ContextPayload], bytes],
+) -> bytes:
+    """Repeatedly drop sections until ``render(payload)`` fits ``hard_cap``.
+
+    Truncation order (LLD-05 §4.3): project_memories → recent_decisions →
+    entities → topics (topics are kept if at all possible).
+    """
+    rendered = render(payload)
+    if len(rendered) <= hard_cap:
+        return rendered
+
+    # 1. trim project_memories
+    p = _with_memories(payload, ())
+    rendered = render(p)
+    if len(rendered) <= hard_cap:
+        return rendered
+
+    # 2. trim recent_decisions
+    p = _with_decisions(p, ())
+    rendered = render(p)
+    if len(rendered) <= hard_cap:
+        return rendered
+
+    # 3. trim entities
+    p = _with_entities(p, ())
+    rendered = render(p)
+    if len(rendered) <= hard_cap:
+        return rendered
+
+    # 4. (as last resort) trim topics too
+    p = _with_topics(p, ())
+    rendered = render(p)
+    return rendered  # caller applies truncate_to_cap safety net
+
+
+def _with_memories(p: ContextPayload,
+                   memories: tuple[str, ...]) -> ContextPayload:
+    return ContextPayload(
+        profile_id=p.profile_id, topics=p.topics, entities=p.entities,
+        recent_decisions=p.recent_decisions, project_memories=memories,
+        generated_at=p.generated_at, version=p.version,
+    )
+
+
+def _with_decisions(p: ContextPayload,
+                    decisions: tuple[str, ...]) -> ContextPayload:
+    return ContextPayload(
+        profile_id=p.profile_id, topics=p.topics, entities=p.entities,
+        recent_decisions=decisions, project_memories=p.project_memories,
+        generated_at=p.generated_at, version=p.version,
+    )
+
+
+def _with_entities(p: ContextPayload,
+                   entities: tuple[tuple[str, int], ...]) -> ContextPayload:
+    return ContextPayload(
+        profile_id=p.profile_id, topics=p.topics, entities=entities,
+        recent_decisions=p.recent_decisions, project_memories=p.project_memories,
+        generated_at=p.generated_at, version=p.version,
+    )
+
+
+def _with_topics(p: ContextPayload,
+                 topics: tuple[tuple[str, float], ...]) -> ContextPayload:
+    return ContextPayload(
+        profile_id=p.profile_id, topics=topics, entities=p.entities,
+        recent_decisions=p.recent_decisions, project_memories=p.project_memories,
+        generated_at=p.generated_at, version=p.version,
+    )
+
+
+__all__ = (
+    "ContextPayload",
+    "DEFAULT_DECISIONS_K",
+    "DEFAULT_MEMORIES_K",
+    "DEFAULT_TOP_K",
+    "RecallFn",
+    "VERSION",
+    "build_payload",
+    "format_decisions",
+    "format_entities",
+    "format_memories",
+    "format_topics",
+    "truncate_payload_for_cap",
+)

package/src/superlocalmemory/hooks/copilot_adapter.py

@@ -0,0 +1,154 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.22 — LLD-05 §6
+
+"""Copilot adapter — writes ``.github/copilot-instructions.md``.
+
+LLD-05 §6. Verified (verification-2026-04-17.md claim 5): plain markdown,
+no frontmatter, soft 2 KB / hard 4 KB cap. Adapter is INACTIVE when the
+project has no ``.github/`` directory — we do not create it ourselves.
+
+Hard rules covered here:
+  - A1 / A2 / A3 / A7: via ``adapter_base.atomic_write``.
+  - A4: soft 2 KB + hard 4 KB cap enforcement.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+from superlocalmemory.core.security_primitives import (
+    PathTraversalError,
+    safe_resolve,
+)
+from superlocalmemory.hooks.adapter_base import (
+    COPILOT_SOFT_BYTES,
+    HARD_BYTES_CAP,
+    WriteResult,
+    atomic_write,
+    record_disable,
+    truncate_to_cap,
+)
+from superlocalmemory.hooks.context_payload import (
+    ContextPayload,
+    RecallFn,
+    build_payload,
+    format_entities,
+    format_topics,
+    truncate_payload_for_cap,
+)
+
+logger = logging.getLogger(__name__)
+
+NAME = "copilot_project"
+TARGET_REL = ".github/copilot-instructions.md"
+
+_BODY_TEMPLATE = (
+    "# SLM Active Brain Context (auto-generated)\n\n"
+    "_Regenerated by SuperLocalMemory every 15 min. Version {version}._\n\n"
+    "## User preferences\n{topics}\n\n"
+    "## Entities\n{entities}\n\n"
+    "## Never do\n"
+    "- Do not modify files under `.slm/`\n"
+    "- Do not commit `*.slm-cache.db`\n"
+)
+
+
+def render_copilot(payload: ContextPayload) -> bytes:
+    return _BODY_TEMPLATE.format(
+        version=payload.version,
+        topics=format_topics(payload),
+        entities=format_entities(payload),
+    ).encode("utf-8")
+
+
+class CopilotAdapter:
+    """Project-scope Copilot adapter."""
+
+    def __init__(
+        self,
+        *,
+        base_dir: Path,
+        sync_log_db: Path,
+        recall_fn: RecallFn,
+        profile_id: str = "default",
+        soft_cap: int = COPILOT_SOFT_BYTES,
+        hard_cap: int = HARD_BYTES_CAP,
+    ) -> None:
+        self._base_dir = Path(base_dir)
+        self._sync_log_db = Path(sync_log_db)
+        self._recall_fn = recall_fn
+        self._profile_id = profile_id
+        self._soft_cap = soft_cap
+        self._hard_cap = hard_cap
+        self.name = NAME
+        self._inactive_until_retry = False
+
+    @property
+    def target_path(self) -> Path:
+        return safe_resolve(self._base_dir, TARGET_REL)
+
+    def is_active(self) -> bool:
+        if os.environ.get("SLM_COPILOT_DISABLED") == "1":
+            return False
+        if self._inactive_until_retry:
+            return False
+        if os.environ.get("SLM_COPILOT_FORCE") == "1":
+            return True
+        # Active iff `.github/` directory already exists in the project.
+        github_dir = self._base_dir / ".github"
+        return github_dir.is_dir()
+
+    def sync(self) -> bool:
+        try:
+            resolved = self.target_path
+        except PathTraversalError:
+            logger.warning("copilot: path-traversal refused")
+            self._inactive_until_retry = True
+            return False
+
+        payload = build_payload(
+            self._profile_id, "project", self._base_dir,
+            recall_fn=self._recall_fn,
+        )
+
+        # Prefer the soft cap; fall back to hard cap.
+        rendered = truncate_payload_for_cap(
+            payload, hard_cap=self._soft_cap, render=render_copilot,
+        )
+        if len(rendered) > self._hard_cap:
+            rendered = truncate_payload_for_cap(
+                payload, hard_cap=self._hard_cap, render=render_copilot,
+            )
+            rendered = truncate_to_cap(rendered, cap=self._hard_cap)
+
+        result: WriteResult = atomic_write(
+            resolved, rendered,
+            adapter_name=self.name,
+            profile_id=self._profile_id,
+            sync_log_db=self._sync_log_db,
+        )
+        return result.wrote
+
+    def disable(self) -> None:
+        try:
+            resolved = self.target_path
+        except PathTraversalError:
+            return
+        if resolved.exists():
+            try:
+                resolved.unlink()
+            except OSError:  # pragma: no cover
+                pass
+        record_disable(
+            resolved,
+            adapter_name=self.name,
+            profile_id=self._profile_id,
+            sync_log_db=self._sync_log_db,
+        )
+        self._inactive_until_retry = True
+
+
+__all__ = ("CopilotAdapter", "NAME", "TARGET_REL", "render_copilot")

package/src/superlocalmemory/hooks/cross_platform_connector.py

@@ -0,0 +1,90 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.22 — LLD-05 §8.2
+
+"""Cross-platform adapter orchestrator (``slm connect``).
+
+LLD-05 §8.2. Holds the active set of adapters, detects which are installed,
+runs a one-shot sync over every active adapter, and flips an individual
+adapter off. Kept in its own module so it can be covered in isolation from
+the legacy ``IDEConnector`` shim that still lives in ``ide_connector.py``
+for backward compatibility with existing SLM users.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Iterable
+
+from superlocalmemory.hooks.adapter_base import Adapter
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterStatus:
+    """Return record for ``CrossPlatformConnector.detect``."""
+    name: str
+    active: bool
+    target_path: str
+
+
+class CrossPlatformConnector:
+    """LLD-05 §8.2 orchestrator.
+
+    A thin coordinator: every adapter knows how to detect itself, sync
+    itself, and disable itself. This class just iterates, catches, and
+    reports. Errors never abort the iteration (A8).
+    """
+
+    def __init__(self, adapters: Iterable[Adapter]) -> None:
+        self._adapters: list[Adapter] = list(adapters)
+
+    @property
+    def adapters(self) -> list[Adapter]:
+        return list(self._adapters)
+
+    def detect(self) -> list[AdapterStatus]:
+        out: list[AdapterStatus] = []
+        for a in self._adapters:
+            try:
+                active = a.is_active()
+            except Exception:
+                active = False
+            try:
+                target = str(a.target_path)
+            except Exception:
+                target = "?"
+            out.append(AdapterStatus(name=a.name, active=active,
+                                     target_path=target))
+        return out
+
+    def connect(self) -> dict[str, str]:
+        """One-shot sync over every active adapter."""
+        results: dict[str, str] = {}
+        for a in self._adapters:
+            try:
+                if not a.is_active():
+                    results[a.name] = "inactive"
+                    continue
+                wrote = a.sync()
+                results[a.name] = "wrote" if wrote else "skipped"
+            except Exception as exc:
+                logger.warning("adapter %s failed: %s", a.name, exc)
+                results[a.name] = f"error:{type(exc).__name__}"
+        return results
+
+    def disable(self, name: str) -> bool:
+        for a in self._adapters:
+            if a.name == name:
+                try:
+                    a.disable()
+                except Exception as exc:
+                    logger.warning("disable %s failed: %s", name, exc)
+                    return False
+                return True
+        return False
+
+
+__all__ = ("AdapterStatus", "CrossPlatformConnector")