claude-smart 0.2.23 → 0.2.25

package/plugin/src/claude_smart/context_format.py

@@ -0,0 +1,277 @@
+"""Render reflexio preferences + skills as markdown for display or injection."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from claude_smart import cs_cite
+
+
+def _first_nonempty(*values: Any) -> str:
+    """Return the first truthy string value, or an empty string."""
+    for v in values:
+        if isinstance(v, str) and v.strip():
+            return v.strip()
+    return ""
+
+
+def render(
+    *,
+    project_id: str,
+    user_playbooks: Iterable[Any],
+    agent_playbooks: Iterable[Any],
+    profiles: Iterable[Any],
+) -> str:
+    """Render skills + preferences as full audit markdown.
+
+    Empty sections are omitted. When all sections are empty, returns "".
+
+    Args:
+        project_id (str): Displayed in the header so the user can tell
+            which project is in effect.
+        user_playbooks (Iterable[Any]): Skill records scoped to this project
+            (``UserPlaybook`` objects or dicts with the same fields).
+        agent_playbooks (Iterable[Any]): Skill records shared across projects
+            (``AgentPlaybook`` objects or dicts with the same fields).
+        profiles (Iterable[Any]): Iterable of preference records
+            (``UserProfile`` objects or dicts).
+
+    Returns:
+        str: Markdown, or "" when there is nothing to show.
+    """
+    markdown, _ = render_with_registry(
+        project_id=project_id,
+        user_playbooks=user_playbooks,
+        agent_playbooks=agent_playbooks,
+        profiles=profiles,
+    )
+    return markdown
+
+
+def render_with_registry(
+    *,
+    project_id: str,
+    user_playbooks: Iterable[Any],
+    agent_playbooks: Iterable[Any],
+    profiles: Iterable[Any],
+) -> tuple[str, list[dict[str, Any]]]:
+    """Variant of ``render`` that also returns the citation registry.
+
+    Every skill and preference bullet is tagged with a short ``[cs:ID]``
+    prefix. The registry maps those ids back to ``{id, kind, title,
+    content}`` entries so ``events.stop`` can resolve citations into
+    human-readable titles for the dashboard.
+
+    Agent playbooks (cross-project, distilled) are listed before user
+    playbooks (this project's lessons) under one ``### Project-specific
+    skills`` heading. The model doesn't need to reason about the split.
+
+    Args:
+        project_id (str): Displayed in the header so the user can tell
+            which project is in effect.
+        user_playbooks (Iterable[Any]): Skill records scoped to this project.
+        agent_playbooks (Iterable[Any]): Skill records shared across projects.
+        profiles (Iterable[Any]): Iterable of preference records
+            (``UserProfile`` objects or dicts).
+
+    Returns:
+        tuple[str, list[dict[str, Any]]]: ``(markdown, registry_entries)``.
+            When all input lists are empty the markdown is ``""`` and the
+            registry is ``[]``.
+    """
+    playbook_lines, playbook_entries = _format_combined_playbooks(
+        agent_playbooks=agent_playbooks, user_playbooks=user_playbooks
+    )
+    profile_lines, profile_entries = _format_profiles(profiles)
+    if not playbook_lines and not profile_lines:
+        return "", []
+
+    sections: list[str] = [f"## claude-smart — project `{project_id}`"]
+    if playbook_lines:
+        sections.append("### Project-specific skills")
+        sections.extend(playbook_lines)
+    if profile_lines:
+        sections.append("### Project preferences")
+        sections.extend(profile_lines)
+    sections.append(cs_cite.CITATION_INSTRUCTION)
+    return "\n".join(sections) + "\n", playbook_entries + profile_entries
+
+
+def render_inline(
+    *,
+    project_id: str,
+    user_playbooks: Iterable[Any],
+    agent_playbooks: Iterable[Any],
+    profiles: Iterable[Any],
+) -> str:
+    """Render skills + preferences for mid-session injection.
+
+    Same bullet format as ``render`` but with no top-level project header.
+    This block is injected just-in-time alongside an in-flight user prompt or
+    tool call, so the caller already has project context.
+
+    Args:
+        project_id (str): Reserved for future use; currently unused.
+        user_playbooks (Iterable[Any]): Relevance-ranked project-scoped hits.
+        agent_playbooks (Iterable[Any]): Relevance-ranked global hits.
+        profiles (Iterable[Any]): Relevance-ranked preference hits.
+
+    Returns:
+        str: Markdown with ``### Relevant project-specific skills`` and/or
+            ``### Relevant project preferences`` sub-sections, or ``""``
+            when all inputs are empty.
+    """
+    markdown, _ = render_inline_with_registry(
+        project_id=project_id,
+        user_playbooks=user_playbooks,
+        agent_playbooks=agent_playbooks,
+        profiles=profiles,
+    )
+    return markdown
+
+
+def render_inline_with_registry(
+    *,
+    project_id: str,
+    user_playbooks: Iterable[Any],
+    agent_playbooks: Iterable[Any],
+    profiles: Iterable[Any],
+) -> tuple[str, list[dict[str, Any]]]:
+    """Variant of ``render_inline`` that also returns the citation registry.
+
+    Args:
+        project_id (str): Reserved for future use; currently unused.
+        user_playbooks (Iterable[Any]): Relevance-ranked project-scoped hits.
+        agent_playbooks (Iterable[Any]): Relevance-ranked global hits.
+        profiles (Iterable[Any]): Relevance-ranked preference hits.
+
+    Returns:
+        tuple[str, list[dict[str, Any]]]: ``(markdown, registry_entries)``.
+            When all input lists are empty the markdown is ``""`` and the
+            registry is ``[]``.
+    """
+    del project_id  # kept for symmetry with ``render_with_registry``.
+    playbook_lines, playbook_entries = _format_combined_playbooks(
+        agent_playbooks=agent_playbooks, user_playbooks=user_playbooks
+    )
+    profile_lines, profile_entries = _format_profiles(profiles)
+    if not playbook_lines and not profile_lines:
+        return "", []
+    sections: list[str] = []
+    if playbook_lines:
+        sections.append("### Relevant project-specific skills")
+        sections.extend(playbook_lines)
+    if profile_lines:
+        sections.append("### Relevant project preferences")
+        sections.extend(profile_lines)
+    sections.append(cs_cite.CITATION_INSTRUCTION)
+    return "\n".join(sections) + "\n", playbook_entries + profile_entries
+
+
+def _format_combined_playbooks(
+    *,
+    agent_playbooks: Iterable[Any],
+    user_playbooks: Iterable[Any],
+) -> tuple[list[str], list[dict[str, Any]]]:
+    """Render agent playbooks first, then user playbooks, with one shared rank counter."""
+    lines: list[str] = []
+    entries: list[dict[str, Any]] = []
+    rank = 0
+    for pb in agent_playbooks:
+        rank = _append_playbook_bullet(
+            pb, "agent_playbook_id", "agent_playbook", rank, lines, entries
+        )
+    for pb in user_playbooks:
+        rank = _append_playbook_bullet(
+            pb, "user_playbook_id", "user_playbook", rank, lines, entries
+        )
+    return lines, entries
+
+
+def _append_playbook_bullet(
+    pb: Any,
+    id_field: str,
+    source_kind: str,
+    rank: int,
+    lines: list[str],
+    entries: list[dict[str, Any]],
+) -> int:
+    content = _first_nonempty(_field(pb, "content"))
+    if not content:
+        return rank
+    rank += 1
+    trigger = _first_nonempty(_field(pb, "trigger"))
+    rationale = _first_nonempty(_field(pb, "rationale"))
+    real_id = _field(pb, id_field)
+    item_id = cs_cite.rank_id("playbook", rank, real_id)
+    title = _title_from_content(content)
+    bullet = f"- [cs:{item_id}] {content}"
+    if trigger:
+        bullet += f" _(when: {trigger})_"
+    if rationale:
+        bullet += f" — *why:* {rationale}"
+    lines.append(bullet)
+    entries.append(
+        {
+            "id": item_id,
+            "kind": "playbook",
+            "title": title,
+            "content": content,
+            "real_id": str(real_id) if real_id is not None else None,
+            "source_kind": source_kind,
+        }
+    )
+    return rank
+
+
+def _format_profiles(
+    profiles: Iterable[Any],
+) -> tuple[list[str], list[dict[str, Any]]]:
+    lines: list[str] = []
+    entries: list[dict[str, Any]] = []
+    rank = 0
+    for p in profiles:
+        content = _first_nonempty(_field(p, "content"))
+        if not content:
+            continue
+        rank += 1
+        real_id = _field(p, "profile_id")
+        item_id = cs_cite.rank_id("profile", rank, real_id)
+        title = _title_from_content(content)
+        lines.append(f"- [cs:{item_id}] {content}")
+        entries.append(
+            {
+                "id": item_id,
+                "kind": "profile",
+                "title": title,
+                "content": content,
+                "real_id": str(real_id) if real_id is not None else None,
+            }
+        )
+    return lines, entries
+
+
+def _title_from_content(content: str, limit: int = 80) -> str:
+    """Derive a compact human-readable title from a bullet's content.
+
+    Truncates at the first sentence boundary when one falls within the
+    character limit; otherwise hard-trims with an ellipsis. Used only for
+    dashboard display.
+    """
+    text = content.strip()
+    if not text:
+        return ""
+    for terminator in (". ", "\n"):
+        idx = text.find(terminator)
+        if 0 < idx <= limit:
+            return text[:idx].rstrip()
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1].rstrip() + "…"
+
+
+def _field(obj: Any, name: str) -> Any:
+    """Read ``name`` from either an attribute or a dict key."""
+    if isinstance(obj, dict):
+        return obj.get(name)
+    return getattr(obj, name, None)

package/plugin/src/claude_smart/context_inject.py

@@ -0,0 +1,92 @@
+"""Shared "search reflexio, render markdown, emit hookSpecificOutput" pipeline.
+
+PreToolUse and UserPromptSubmit both (a) run a query-aware reflexio
+search, (b) render the hits with ``context_format.render_inline_with_registry``,
+(c) persist the citation registry for the Stop hook to resolve, and
+(d) emit a Claude Code ``hookSpecificOutput.additionalContext`` envelope
+on stdout. This module owns that shared pipeline so the two hook
+handlers keep exactly one source of truth for the injection contract —
+the envelope shape, the registry schema, and the ordering of
+``ensure_installed`` / ``append_injected``.
+
+The caller remains responsible for handler-specific framing (PreToolUse
+needs ``hook.emit_continue()`` on the empty path; UserPromptSubmit wraps
+the search in ``try/except`` so a failed reflexio never breaks a user's
+turn) — see the two call sites for the small policy differences.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+
+from claude_smart import context_format, cs_cite, state
+from claude_smart.reflexio_adapter import Adapter
+
+
+def emit_context(
+    *,
+    session_id: str,
+    project_id: str,
+    query: str,
+    hook_event_name: str,
+    top_k: int,
+    adapter: Adapter | None = None,
+) -> bool:
+    """Search reflexio, render hits, emit ``additionalContext`` on stdout.
+
+    Args:
+        session_id (str): Claude Code session id; used to scope the
+            per-session citation registry.
+        project_id (str): reflexio ``user_id`` for this repo.
+        query (str): Free-text query routed to reflexio's unified
+            ``/api/search`` endpoint, which fans out to user playbooks
+            (project-scoped), agent playbooks (global), and preferences
+            (project-scoped) server-side.
+        hook_event_name (str): ``"PreToolUse"`` or ``"UserPromptSubmit"``;
+            echoed verbatim in the hook envelope so Claude Code attributes
+            the context to the right event.
+        top_k (int): Cap on hits per collection.
+        adapter (Adapter | None): Injection seam for tests. A fresh
+            ``Adapter()`` is used when ``None``.
+
+    Returns:
+        bool: ``True`` when markdown was emitted to stdout; ``False``
+            when the search returned nothing to inject.
+    """
+    user_playbooks, agent_playbooks, profiles = (adapter or Adapter()).search_all(
+        project_id=project_id,
+        query=query,
+        top_k=top_k,
+    )
+    markdown, registry = context_format.render_inline_with_registry(
+        project_id=project_id,
+        user_playbooks=user_playbooks,
+        agent_playbooks=agent_playbooks,
+        profiles=profiles,
+    )
+    if not markdown:
+        return False
+
+    cs_cite.ensure_installed()
+    state.append_injected(
+        session_id,
+        (dict(entry, ts=int(time.time())) for entry in registry),
+    )
+
+    sys.stdout.write(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": hook_event_name,
+                    "additionalContext": markdown,
+                }
+            }
+        )
+    )
+    sys.stdout.write("\n")
+    return True
+
+
+__all__ = ["emit_context"]

package/plugin/src/claude_smart/cs_cite.py

@@ -0,0 +1,236 @@
+"""Support helpers for claude-smart citation tracking.
+
+Context injected by UserPromptSubmit / PreToolUse tags each skill and
+preference bullet with a rank-based id fingerprinted by the underlying
+real id (``[cs:s1-1a2b]`` for the first skill whose
+``user_playbook_id`` starts with ``1a2b``, ``[cs:p2-c3d4]`` for the
+second preference). The injected instruction asks the assistant to end
+impactful replies with a marker like::
+
+    ✨ 1 claude-smart learning applied [cs:s1-1a2b]
+
+The Stop hook later scans the assistant text for those markers and resolves
+the ids against a per-session registry persisted at
+``~/.claude-smart/sessions/<session_id>.injected.jsonl``. Legacy ``cs-cite``
+Bash tool calls are still accepted as a fallback for older instructions.
+
+Why rank + fingerprint: rank alone resets at every injection, so a
+later injection's ``s1`` would silently overwrite an earlier entry in
+the append-only registry — if Claude cited ``s1`` across a turn
+boundary, the resolver would pick the wrong skill. Appending the
+first four alphanumeric chars of the real id makes the id stable
+across injections in the common case (distinct real ids → distinct
+fingerprints), so cross-injection collisions become rare.
+
+This module holds:
+
+- ``rank_id``: ``p{n}-{fp}`` / ``s{n}-{fp}`` tag for a given
+  (kind, rank, real_id) tuple. Fingerprint is omitted when no real id
+  is available. ``p`` is preference, ``s`` is skill.
+- ``CITATION_CMD_RE``: regex matching a valid legacy ``cs-cite`` command line.
+- ``ensure_installed``: idempotent copy of ``plugin/bin/cs-cite`` to
+  ``~/.claude-smart/bin/cs-cite`` with the executable bit set.
+- ``CITATION_INSTRUCTION``: the trailer text appended to injected context
+  so the assistant knows when and how to emit the citation marker.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import stat as stat_
+from pathlib import Path
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+_THIS_DIR = Path(__file__).resolve().parent
+_PLUGIN_ROOT = _THIS_DIR.parents[1]  # plugin/src/claude_smart/ -> plugin/
+_SOURCE_SCRIPT = _PLUGIN_ROOT / "bin" / "cs-cite"
+_INSTALL_DIR = Path.home() / ".claude-smart" / "bin"
+INSTALL_PATH = _INSTALL_DIR / "cs-cite"
+
+_FINGERPRINT_LEN = 4
+
+# Match a bare `cs-cite <ids>` invocation. Ids are rank tokens of the
+# form `p<N>` (preference) or `s<N>` (skill) with an optional
+# `-<fp>` fingerprint (1-4 alphanumeric chars), optionally
+# `cs:`-prefixed (since bullets render as `[cs:p1-ab12]` and the model
+# often copies the tag verbatim). The `(?i:...)` inline flags make the
+# prefix, kind letter, and fingerprint case-insensitive so `CS:P1-AB12`
+# is accepted — matching the `re.IGNORECASE` used by the standalone
+# `cs-cite` script. Tokens may be comma- and/or whitespace-separated.
+# Chained commands (&&, |, ;) and extra trailing tokens remain rejected
+# by the anchored `\s*$` terminator so accidental mentions don't
+# register as citations.
+_ID_TOKEN = r"(?i:cs:)?(?i:[ps])\d+(?:-(?i:[a-z0-9]){1,4})?"
+_ID_SEP = r"[,\s]+"
+CITATION_CMD_RE = re.compile(
+    rf"^\s*(?:[^\s]*/)?cs-cite\s+({_ID_TOKEN}(?:{_ID_SEP}{_ID_TOKEN})*)\s*$"
+)
+_CLEAN_ID_RE = re.compile(r"^(?i:cs:)?((?i:[ps])\d+(?:-(?i:[a-z0-9]){1,4})?)$")
+_SPLIT_RE = re.compile(_ID_SEP)
+_TEXT_CITATION_LINE_RE = re.compile(
+    r"(?im)^\s*✨\s+\d+\s+claude-smart learning(?:s)? applied\s+"
+    r"\[cs:(?P<ids>[^\]]+)\]\s*$"
+)
+
+CITATION_INSTRUCTION = (
+    "_First, fully answer the user — citation does not change what or how "
+    "you reply. Then, as a final step, consider whether to cite: if — and "
+    "only if — an injected `[cs:…]` item materially changed your reply "
+    "(different wording, action, or conclusion than you would have produced "
+    "without it), append exactly one final citation line after your answer. "
+    "Do not call `cs-cite` or any other tool for citations. Ids come verbatim "
+    "from the `[cs:…]` tags — keep the leading `p` (preference) or `s` "
+    "(skill) and the `-<fp>` suffix. Use this exact format for one id: "
+    "`✨ 1 claude-smart learning applied [cs:s1-ab12]`. Use this exact format "
+    "for multiple ids: `✨ 2 claude-smart learnings applied [cs:s1-ab12,p2-cd34]`, "
+    "where the number is the count of ids in the brackets. "
+    "Never emit a standalone wrapper like `✨s1-ab12✨` or `✨abc123✨`; "
+    "those are not claude-smart citations and cannot be resolved. "
+    "Default is to skip. If an item is merely on-topic, confirms what you "
+    "already planned, or your reply would read the same without it, do not "
+    "cite — end the turn normally with your reply. When unsure, skip. Do "
+    "not add any other text, tool calls, or role markers after the final "
+    "citation line._"
+)
+
+
+def _fingerprint(real_id: Any) -> str:
+    """Return the first ``_FINGERPRINT_LEN`` alphanumeric chars of ``real_id``.
+
+    The fingerprint disambiguates rank ids across injections: two
+    injections both producing ``s1`` for different skills will still
+    yield distinct tags when their real ids have different prefixes.
+
+    Args:
+        real_id: The underlying ``user_playbook_id`` or ``profile_id``.
+            Accepts anything ``str()`` handles (int, UUID, etc.).
+            ``None`` yields an empty string.
+
+    Returns:
+        str: Up to 4 lowercase alphanumeric chars; empty when the real
+            id has no alphanumeric characters or is ``None``.
+    """
+    if real_id is None:
+        return ""
+    return "".join(c for c in str(real_id).lower() if c.isalnum())[:_FINGERPRINT_LEN]
+
+
+def rank_id(kind: str, rank: int, real_id: Any = None) -> str:
+    """Return the citation id for a skill or preference item.
+
+    Format is ``{letter}{rank}-{fingerprint}`` where ``letter`` is ``p``
+    for preferences and ``s`` for skills, ``rank`` is the 1-based
+    position within the current retrieval batch, and ``fingerprint`` is
+    up to 4 alphanumeric chars derived from ``real_id``. The fingerprint
+    is omitted when no real id is available (falling back to the rank
+    form ``s1`` / ``p1``).
+
+    Args:
+        kind: ``"playbook"`` or ``"profile"``. Unknown values raise
+            ``ValueError`` — callers never build registry entries for
+            other kinds.
+        rank: 1-based position within the retrieval batch.
+        real_id: The underlying ``user_playbook_id`` or ``profile_id``
+            used to derive the fingerprint suffix. Optional.
+
+    Returns:
+        str: ``p<rank>-<fp>`` for preferences, ``s<rank>-<fp>`` for
+            skills. Suffix is omitted when the real id yields no
+            alphanumeric fingerprint.
+
+    Raises:
+        ValueError: If ``kind`` is not ``"profile"`` or ``"playbook"``.
+    """
+    if kind == "profile":
+        prefix = "p"
+    elif kind == "playbook":
+        prefix = "s"
+    else:
+        raise ValueError(f"unknown citation kind: {kind!r}")
+    fp = _fingerprint(real_id)
+    return f"{prefix}{rank}-{fp}" if fp else f"{prefix}{rank}"
+
+
+def parse_citation_command(command: str) -> list[str]:
+    """Extract citation ids from a ``cs-cite`` Bash command string.
+
+    Returns an empty list when the command does not match the expected
+    shape (chained commands, extra arguments, or anything other than a
+    bare ``cs-cite <ids>`` invocation are rejected to avoid false
+    positives from accidental mentions).
+
+    Args:
+        command: The raw ``input.command`` value from a Bash tool_use
+            block.
+
+    Returns:
+        list[str]: Lowercase rank ids (e.g. ``"p1"``, ``"s3"``), in the
+            order Claude cited them. Empty when the command does not
+            match.
+    """
+    match = CITATION_CMD_RE.match(command or "")
+    if not match:
+        return []
+    return _parse_id_tokens(match.group(1))
+
+
+def parse_text_citations(text: str) -> list[str]:
+    """Extract Codex text-only citation ids from a final learning marker line.
+
+    The parser intentionally only accepts lines containing the visual
+    ``claude-smart learning(s) applied`` marker, so ordinary references to
+    injected ``[cs:...]`` ids inside an answer do not count as citations.
+    When multiple matching lines exist, the last one wins because the
+    instruction requires the citation marker to be final.
+    """
+    matches = list(_TEXT_CITATION_LINE_RE.finditer(text or ""))
+    if not matches:
+        return []
+    return _parse_id_tokens(matches[-1].group("ids"))
+
+
+def _parse_id_tokens(raw_ids: str) -> list[str]:
+    ids: list[str] = []
+    for tok in _SPLIT_RE.split(raw_ids.strip()):
+        if clean := _CLEAN_ID_RE.match(tok):
+            ids.append(clean.group(1).lower())
+    return ids
+
+
+def ensure_installed() -> Path:
+    """Idempotently install ``cs-cite`` into ``~/.claude-smart/bin/``.
+
+    Called from every PreToolUse / UserPromptSubmit inject, so we
+    short-circuit when the target file already exists with
+    the executable bit set — the steady-state path is one ``stat`` syscall
+    instead of mkdir + copy + stat + chmod. Keying on filesystem state
+    (rather than a module-level boolean) keeps test isolation working when
+    tests monkeypatch ``INSTALL_PATH`` to a fresh tmpdir.
+
+    Never raises — filesystem errors are logged at DEBUG and the caller
+    proceeds with injection regardless (the citation feature degrades to
+    silent if the script is unreachable).
+
+    Returns:
+        Path: Target path, whether or not install succeeded.
+    """
+    try:
+        if (
+            INSTALL_PATH.is_file()
+            and INSTALL_PATH.stat().st_mode & stat_.S_IXUSR
+            and _SOURCE_SCRIPT.is_file()
+            and INSTALL_PATH.read_bytes() == _SOURCE_SCRIPT.read_bytes()
+        ):
+            return INSTALL_PATH
+        _INSTALL_DIR.mkdir(parents=True, exist_ok=True)
+        if _SOURCE_SCRIPT.is_file():
+            shutil.copy2(_SOURCE_SCRIPT, INSTALL_PATH)
+            mode = INSTALL_PATH.stat().st_mode
+            INSTALL_PATH.chmod(mode | stat_.S_IXUSR | stat_.S_IXGRP | stat_.S_IXOTH)
+    except OSError as exc:
+        _LOGGER.debug("cs-cite install failed: %s", exc)
+    return INSTALL_PATH

package/plugin/src/claude_smart/events/__init__.py

@@ -0,0 +1 @@
+"""Event handlers — one module per Claude Code hook event."""