@heytherevibin/skillforge 0.10.0 → 0.11.7

package/python/app/tools_cli.py

@@ -0,0 +1,276 @@
+"""
+CLI parity for MCP tools (non-MCP callers: scripts, terminals, CI).
+
+Dispatches through the same MCPServer tool handlers after a one-time router load.
+Does not speak JSON-RPC; use ``skillforge mcp`` for MCP hosts.
+
+Examples:
+  skillforge tools search \"refactor typescript\"
+  skillforge tools explain --prompt=\"debug routing\" --project-root \"$PWD\"
+  skillforge tools get --skill-name my_skill --format card
+  skillforge tools catalog
+  skillforge tools capabilities --json
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from typing import Any
+
+from app.mcp_server import MCPServer
+
+
+def _die(msg: str, code: int = 2) -> None:
+    print(msg, file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _base_payload(ns: argparse.Namespace) -> dict[str, Any]:
+    d: dict[str, Any] = {}
+    if getattr(ns, "project_root", None) and str(ns.project_root).strip():
+        d["project_root"] = str(ns.project_root).strip()
+    if getattr(ns, "user_id", None) and str(ns.user_id).strip():
+        d["user_id"] = str(ns.user_id).strip()
+    return d
+
+
+def _merged(ns: argparse.Namespace, extra: dict[str, Any]) -> dict[str, Any]:
+    return {**_base_payload(ns), **extra}
+
+
+async def _run_tool(server: MCPServer, tool: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    return await server.handle_tools_call({"name": tool, "arguments": arguments})
+
+
+def _emit(payload: dict[str, Any], *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, indent=2, default=str))
+    else:
+        blocks = payload.get("content") or []
+        text = ""
+        if blocks and isinstance(blocks[0], dict) and blocks[0].get("type") == "text":
+            text = str(blocks[0].get("text") or "")
+        sys.stdout.write(text)
+        if text and not text.endswith("\n"):
+            sys.stdout.write("\n")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="skillforge tools",
+        description=(
+            "Invoke MCP-equivalent Skillforge tools from the shell. "
+            "Uses the same Python handlers as ``skillforge mcp`` (shared router + DB)."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "CLI mapping: MCP route_skills → ``skillforge route`` "
+            "(``tools`` exposes the remaining published tools verbatim)."
+        ),
+    )
+    p.add_argument(
+        "--project-root",
+        metavar="PATH",
+        help="Workspace root (per-repo ~/.skillforge); else SKILLFORGE_PROJECT_ROOT",
+    )
+    p.add_argument("--user-id", metavar="ID", help="Namespace for weights / events (matches MCP user_id)")
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="Print full MCP tool payload (content + _meta) as JSON on stdout",
+    )
+    sub = p.add_subparsers(dest="tool", metavar="COMMAND", required=True)
+
+    sp = sub.add_parser("search", help="Embedding shortlist for a query (MCP: search_skills)")
+    sp.add_argument("query", nargs="+", help="Search text")
+    sp.add_argument("--limit", type=int, metavar="N", help="Max skills (default server TOP_K; cap 50)")
+
+    ep = sub.add_parser("explain", help="Routing diagnostics without session writes (MCP: explain_route)")
+    ep.add_argument("--prompt", required=True, help="Task text")
+    ep.add_argument("--limit", type=int, metavar="N")
+    ep.add_argument(
+        "--conversation",
+        metavar="FILE.json",
+        help="Optional JSON array of message objects (same shape as MCP conversation)",
+    )
+
+    gp = sub.add_parser("get", help="Fetch one catalog skill by id (MCP: get_skill)")
+    gp.add_argument("--skill-name", required=True, metavar="NAME")
+    gp.add_argument("--format", choices=("card", "summary", "full"), default="full")
+    gp.add_argument("--max-chars", type=int, default=0, metavar="N")
+
+    sub.add_parser("catalog", help="Skills + usage stats (MCP: list_skills)")
+
+    fb = sub.add_parser("feedback", help="Thumb up/down (MCP: skill_feedback)")
+    fb.add_argument("--skill-name", required=True)
+    fb.add_argument("--thumbs", type=int, choices=(-1, 1), required=True)
+    fb.add_argument("--session-id", default="", metavar="ID")
+
+    dis = sub.add_parser("disable", help="Exclude or restore a catalog skill from routing (MCP: disable_skill)")
+    dis.add_argument("--skill-name", required=True)
+    g = dis.add_mutually_exclusive_group(required=True)
+    g.add_argument("--off", dest="disabled", action="store_true", help="Disable routing to this skill")
+    g.add_argument("--on", dest="disabled", action="store_false", help="Re-enable routing")
+
+    ref = sub.add_parser("referenced", help="Increment reference/stat count (MCP: skill_referenced)")
+    ref.add_argument("--skill-name", required=True)
+
+    mp = sub.add_parser("materialize", help="Write project-local skillforge stubs (MCP: materialize_project)")
+    mp.add_argument("--root", dest="mat_root", required=True, metavar="PATH", help="Project root directory")
+    mp.add_argument("--names", required=True, metavar="CSV", help="Comma-separated skill ids from routing")
+    mp.add_argument(
+        "--hosts",
+        choices=("auto", "both", "cursor", "claude_code"),
+        default="auto",
+        help="Which host trees to write (same as MCP)",
+    )
+    mp.add_argument(
+        "--no-merge",
+        action="store_true",
+        help="If set, refuse to overwrite existing managed files where applicable",
+    )
+
+    bp = sub.add_parser(
+        "bootstrap",
+        help="route_skills then materialize (blocked when ROUTER_MODE=host; MCP: skillforge_bootstrap)",
+    )
+    bp.add_argument("--prompt", required=True)
+    bp.add_argument("--root", dest="bootstrap_root", required=True, metavar="PATH")
+    bp.add_argument("--conversation", metavar="FILE.json")
+    bp.add_argument("--session-id", default="", metavar="ID")
+    bp.add_argument(
+        "--hosts",
+        choices=("auto", "both", "cursor", "claude_code"),
+        default="auto",
+    )
+    bp.add_argument("--no-merge", action="store_true")
+    bp.add_argument(
+        "--include-project-rag",
+        action="store_true",
+        help="Attach indexed project chunks (requires index + project root)",
+    )
+
+    sub.add_parser("capabilities", help="Bootstrap bundle + tool list JSON (MCP: capabilities)")
+    sub.add_parser("router-status", help="Read-only router/env snapshot (MCP: get_router_status)")
+
+    ip = sub.add_parser("index-status", help="Project index stats from orchestrator DB (MCP: project_index_status)")
+    ip.add_argument("--root", dest="idx_root", required=True, metavar="PATH")
+
+    sub.add_parser("weights-snapshot", help="skill_weights rows as JSON (MCP: weights_snapshot)")
+
+    ev = sub.add_parser("events-recent", help="Recent SQLite events (MCP: events_recent)")
+    ev.add_argument("--limit", type=int, default=25, metavar="N")
+    ev.add_argument("--event-type", default="", metavar="TYPE")
+
+    return p
+
+
+def _parse_conversation(path: str) -> list[Any]:
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, list):
+        _die("--conversation JSON must be an array")
+    return data
+
+
+async def _async_main(raw: list[str]) -> int:
+    parser = build_parser()
+    ns = parser.parse_args(raw)
+
+    server = MCPServer()
+    await server.setup()
+
+    if ns.tool == "search":
+        q = " ".join(ns.query).strip()
+        args = _merged(ns, {"query": q})
+        if ns.limit is not None:
+            args["limit"] = ns.limit
+        payload = await _run_tool(server, "search_skills", args)
+    elif ns.tool == "explain":
+        args = _merged(ns, {"prompt": ns.prompt.strip()})
+        if ns.limit is not None:
+            args["limit"] = ns.limit
+        if ns.conversation:
+            args["conversation"] = _parse_conversation(ns.conversation)
+        payload = await _run_tool(server, "explain_route", args)
+    elif ns.tool == "get":
+        args = _merged(
+            ns,
+            {"skill_name": ns.skill_name, "format": ns.format, "max_chars": ns.max_chars},
+        )
+        payload = await _run_tool(server, "get_skill", args)
+    elif ns.tool == "catalog":
+        payload = await _run_tool(server, "list_skills", _merged(ns, {}))
+    elif ns.tool == "feedback":
+        args = _merged(
+            ns,
+            {"skill_name": ns.skill_name, "thumbs": ns.thumbs, "session_id": ns.session_id or ""},
+        )
+        payload = await _run_tool(server, "skill_feedback", args)
+    elif ns.tool == "disable":
+        args = _merged(ns, {"skill_name": ns.skill_name, "disabled": bool(ns.disabled)})
+        payload = await _run_tool(server, "disable_skill", args)
+    elif ns.tool == "referenced":
+        args = _merged(ns, {"skill_name": ns.skill_name})
+        payload = await _run_tool(server, "skill_referenced", args)
+    elif ns.tool == "materialize":
+        names = [n.strip() for n in ns.names.replace(",", " ").split() if n.strip()]
+        args_m = _merged(
+            ns,
+            {
+                "project_root": str(ns.mat_root).strip(),
+                "skill_names": names,
+                "merge": not ns.no_merge,
+                "hosts": ns.hosts,
+            },
+        )
+        payload = await server.handle_tools_call({"name": "materialize_project", "arguments": args_m})
+    elif ns.tool == "bootstrap":
+        conv: list[Any] = []
+        if ns.conversation:
+            conv = _parse_conversation(ns.conversation)
+        sid = str(ns.session_id).strip()
+        args_b = _merged(
+            ns,
+            {
+                "prompt": ns.prompt,
+                "project_root": str(ns.bootstrap_root).strip(),
+                "conversation": conv,
+                "session_id": sid if sid else None,
+                "merge": not ns.no_merge,
+                "hosts": ns.hosts,
+                "include_project_rag": bool(ns.include_project_rag),
+            },
+        )
+        payload = await server.handle_tools_call({"name": "skillforge_bootstrap", "arguments": args_b})
+    elif ns.tool == "capabilities":
+        payload = await server.handle_tools_call({"name": "capabilities", "arguments": _merged(ns, {})})
+    elif ns.tool == "router-status":
+        payload = await server.handle_tools_call({"name": "get_router_status", "arguments": _merged(ns, {})})
+    elif ns.tool == "index-status":
+        args_i = _merged(ns, {"project_root": str(ns.idx_root).strip()})
+        payload = await server.handle_tools_call({"name": "project_index_status", "arguments": args_i})
+    elif ns.tool == "weights-snapshot":
+        payload = await server.handle_tools_call({"name": "weights_snapshot", "arguments": _merged(ns, {})})
+    elif ns.tool == "events-recent":
+        et = str(ns.event_type).strip()
+        args_e = _merged(ns, {"limit": ns.limit, **({"event_type": et} if et else {})})
+        payload = await server.handle_tools_call({"name": "events_recent", "arguments": args_e})
+    else:  # pragma: no cover
+        parser.error(f"unknown tool: {ns.tool}")
+
+    _emit(payload, as_json=ns.json)
+    if payload.get("isError"):
+        return 2
+    return 0
+
+
+def main() -> None:
+    code = asyncio.run(_async_main(sys.argv[1:]))
+    raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()

package/python/fixtures/route_eval/smoke.json

@@ -13,6 +13,11 @@
       "id": "docker-patterns",
       "prompt": "docker compose healthcheck restart policy and rollout",
       "expect_in_candidates": ["docker-patterns"]
+    },
+    {
+      "id": "postgres-patterns",
+      "prompt": "PostgreSQL deadlock investigation and slow query indexing",
+      "expect_in_candidates": ["postgres-patterns"]
     }
   ]
 }

package/python/requirements.txt

@@ -1,4 +1,5 @@
 anthropic>=0.39
+openai>=1.40.0
 sentence-transformers>=2.7
 numpy>=1.26
 rank-bm25>=0.2.2

package/python/tests/test_capabilities_bundle.py

@@ -0,0 +1,33 @@
+"""Session bootstrap MCP bundle helpers."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from app.mcp_contract import MCP_RESPONSE_SCHEMA_VERSION
+from app.mcp_operator import MCP_PUBLISHED_TOOL_NAMES, build_capabilities_bundle
+
+
+def test_build_capabilities_bundle_includes_ordered_tools_and_schema() -> None:
+    router = SimpleNamespace(
+        anthropic=None,
+        context_mode="chunks",
+        _hybrid_mode="off",
+        _by_name=None,
+    )
+    bundle = build_capabilities_bundle(router, skill_count=3)
+    assert bundle["bundle_version"] == "1"
+    assert bundle["mcp_response_schema_version"] == MCP_RESPONSE_SCHEMA_VERSION
+    assert bundle["mcp_tools"] == list(MCP_PUBLISHED_TOOL_NAMES)
+    assert bundle["progressive_loading"]["get_skill_formats"] == ["card", "summary", "full"]
+    uep = bundle["user_env_profile"]
+    assert uep["validate_command"] == "skillforge config validate"
+    assert "path_command" in uep and "init_command" in uep
+    snap = bundle["router_snapshot"]
+    assert snap["skills_loaded_count"] == 3
+
+
+def test_capabilities_tool_names_cover_expected_surface() -> None:
+    essential = {"route_skills", "capabilities", "get_router_status", "events_recent"}
+    missing = essential - set(MCP_PUBLISHED_TOOL_NAMES)
+    assert not missing

package/python/tests/test_materialize_hosts.py

@@ -0,0 +1,108 @@
+"""materialize_project hosts= cursor | claude_code | both."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from app.materialize import (
+    infer_materialize_hosts_from_mcp_client,
+    materialize_project_files,
+    normalize_materialize_hosts,
+    resolve_materialize_hosts_argument,
+)
+
+
+def test_infer_materialize_hosts_from_mcp_client() -> None:
+    assert infer_materialize_hosts_from_mcp_client("cursor-vscode-fork", "") == "cursor"
+    assert infer_materialize_hosts_from_mcp_client("", "Claude Code") == "claude_code"
+    assert infer_materialize_hosts_from_mcp_client("", "", environ={}) == "both"
+    assert infer_materialize_hosts_from_mcp_client("", "", environ={"CURSOR_AGENT": "1"}) == "cursor"
+
+
+def test_resolve_materialize_hosts_argument_explicit_wins_inference() -> None:
+    mode, meta = resolve_materialize_hosts_argument(
+        "both",
+        client_name="cursor-ai",
+        environ={"SKILLFORGE_MATERIALIZE_HOSTS": "claude_code"},
+    )
+    assert mode == "both"
+    assert meta["hosts_resolution"] == "explicit"
+
+
+def test_resolve_materialize_hosts_argument_auto_infer() -> None:
+    mode, meta = resolve_materialize_hosts_argument(
+        "auto",
+        client_name="Cursor IDE",
+    )
+    assert mode == "cursor"
+    assert meta["hosts_resolution"] == "inferred"
+
+
+def test_resolve_materialize_hosts_argument_env_when_auto() -> None:
+    mode, meta = resolve_materialize_hosts_argument(
+        None,
+        client_name="",
+        environ={"SKILLFORGE_MATERIALIZE_HOSTS": "cursor"},
+    )
+    assert mode == "cursor"
+    assert meta["hosts_resolution"] == "environment"
+
+
+def test_resolve_infer_beats_blank_env_skillforge_var_not_set_on_client() -> None:
+    """Client name wins before falling back when SKILLFORGE_MATERIALIZE_HOSTS absent."""
+    mode, meta = resolve_materialize_hosts_argument(
+        None,
+        client_name="com.anthropic.claude-code-helper",
+        client_title="",
+        environ={},
+    )
+    assert mode == "claude_code"
+    assert meta["hosts_resolution"] == "inferred"
+
+
+def test_resolve_environment_overrides_client_inference() -> None:
+    mode, meta = resolve_materialize_hosts_argument(
+        None,
+        client_name="Cursor IDE",
+        environ={"SKILLFORGE_MATERIALIZE_HOSTS": "claude_code"},
+    )
+    assert mode == "claude_code"
+    assert meta["hosts_resolution"] == "environment"
+
+
+def test_normalize_materialize_hosts() -> None:
+    assert normalize_materialize_hosts(None) == "both"
+    assert normalize_materialize_hosts("  BOTH  ") == "both"
+    assert normalize_materialize_hosts("cursor") == "cursor"
+    assert normalize_materialize_hosts("claude-code") == "claude_code"
+    assert normalize_materialize_hosts("claude") == "claude_code"
+    with pytest.raises(ValueError, match="hosts must be"):
+        normalize_materialize_hosts("vscode")
+
+
+def test_hosts_cursor_writes_no_claude_paths(tmp_path) -> None:
+    root = tmp_path / "p"
+    root.mkdir()
+    out = materialize_project_files(str(root), ["x"], {"x": "y"}, hosts="cursor")
+    rel = {Path(p).as_posix() for p in out["written"]}
+    assert ".cursor/commands/skillforge.md" in rel
+    assert ".cursor/rules/skillforge.mdc" in rel
+    assert "docs/SKILLFORGE-PRD.md" in rel
+    assert ".claude/commands/skillforge.md" not in rel
+    assert "CLAUDE.md" not in rel
+    assert not (root / ".claude").exists()
+
+
+def test_hosts_claude_code_writes_no_cursor_paths(tmp_path) -> None:
+    root = tmp_path / "p"
+    root.mkdir()
+    out = materialize_project_files(str(root), ["x"], {"x": "y"}, hosts="claude_code")
+    rel = {Path(p).as_posix() for p in out["written"]}
+    assert ".claude/commands/skillforge.md" in rel
+    assert "CLAUDE.md" in rel
+    assert "docs/SKILLFORGE-PRD.md" in rel
+    assert ".cursor/commands/skillforge.md" not in rel
+    assert ".cursor/rules/skillforge.mdc" not in rel
+    assert not (root / ".cursor").exists()

package/python/tests/test_mcp_contract.py

@@ -138,7 +138,7 @@ def test_build_route_skills_meta_error_field() -> None:
 
 
 def test_build_route_skills_meta_includes_route_quality() -> None:
-    rq = {"schema": "route_quality/1", "picked_count": 1}
+    rq = {"schema": "route_quality/2", "picked_count": 1}
     meta = build_route_skills_meta(
         result={
             "candidates": [],

package/python/tests/test_mcp_initialize_clientinfo.py

@@ -0,0 +1,26 @@
+"""MCP initialize stores clientInfo for materialize hosts inference."""
+
+from __future__ import annotations
+
+from app.mcp_server import MCPServer
+
+
+def test_handle_initialize_records_client_info() -> None:
+    s = MCPServer()
+    s.handle_initialize(
+        {
+            "protocolVersion": "2024-11-05",
+            "clientInfo": {"name": "cursor-ai", "title": "Workspace"},
+        }
+    )
+    assert s._mcp_client_name == "cursor-ai"
+    assert s._mcp_client_title == "Workspace"
+
+
+def test_handle_initialize_missing_client_info_resets() -> None:
+    s = MCPServer()
+    s.handle_initialize({"clientInfo": {"name": "cursor-temp"}})
+    assert s._mcp_client_name == "cursor-temp"
+    s.handle_initialize({})
+    assert s._mcp_client_name == ""
+    assert s._mcp_client_title == ""

package/python/tests/test_mcp_operator.py

@@ -0,0 +1,84 @@
+"""Unit tests for MCP operator helpers (no MCP server lifecycle)."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+
+from app.mcp_operator import (
+    EVENTS_MARKDOWN_PREVIEW_MAX_LINES,
+    build_router_status_dict,
+    events_recent_rows,
+    format_events_markdown,
+    project_index_status_dict,
+)
+from app.npm_pkg_version import clear_version_cache_for_tests
+from app.project_index import ensure_project_index_schema
+
+
+def test_build_router_status_dict_without_router(monkeypatch) -> None:
+    monkeypatch.delenv("SKILLFORGE_MCP_SERVER_VERSION", raising=False)
+    clear_version_cache_for_tests()
+    snap = build_router_status_dict(None, skill_count=0)
+    assert snap["skills_loaded_count"] == 0
+    assert snap["anthropic_available"] is False
+    assert "skillforge_router_mode" in snap
+    assert "mcp_server_semver" in snap
+    semver = snap["mcp_server_semver"]
+    assert isinstance(semver, str) and len(semver.split(".")) == 3
+
+
+def test_format_events_markdown_truncation_notice() -> None:
+    many = [{"ts": 1.0, "session_id": "sess", "event_type": "route", "payload": {}}]
+    md = format_events_markdown(many * (EVENTS_MARKDOWN_PREVIEW_MAX_LINES + 10))
+    assert "_meta.rows" in md
+    assert "truncated" in md.lower()
+
+
+def test_project_index_status_counts(tmp_path, monkeypatch) -> None:
+    db = tmp_path / "orch.db"
+    con = sqlite3.connect(str(db))
+    ensure_project_index_schema(con)
+    con.execute(
+        "INSERT INTO project_chunks (path,line_start,line_end,mtime,file_size,content,embedding) "
+        "VALUES (?,?,?,?,?,?,?)",
+        ("a.py", 1, 2, 0.0, 10, "x", b"\0\0\0\0"),
+    )
+    con.execute(
+        "INSERT INTO project_chunks (path,line_start,line_end,mtime,file_size,content,embedding) "
+        "VALUES (?,?,?,?,?,?,?)",
+        ("b.py", 1, 2, 0.0, 10, "y", b"\0\0\0\0"),
+    )
+    con.commit()
+    m = project_index_status_dict(con)
+    assert m["chunk_count"] == 2
+    assert m["distinct_paths"] == 2
+    con.close()
+
+
+def test_events_recent_rows_filter_user_and_type(tmp_path) -> None:
+    db = tmp_path / "e.db"
+    con = sqlite3.connect(str(db))
+    con.execute(
+        """CREATE TABLE events (
+            id TEXT PRIMARY KEY, ts REAL, user_id TEXT, session_id TEXT, event_type TEXT, payload TEXT
+        )"""
+    )
+    con.execute(
+        "INSERT INTO events VALUES (?,?,?,?,?,?)",
+        ("1", 10.0, "u", "s", "route", json.dumps({"picked": ["a"]})),
+    )
+    con.execute(
+        "INSERT INTO events VALUES (?,?,?,?,?,?)",
+        ("2", 20.0, "u", "s", "feedback", json.dumps({"skill": "b"})),
+    )
+    con.execute(
+        "INSERT INTO events VALUES (?,?,?,?,?,?)",
+        ("3", 30.0, "other", "s", "route", "{}"),
+    )
+    con.commit()
+    rows = events_recent_rows(con, limit=10, user_id="u", event_type="route")
+    assert len(rows) == 1
+    assert rows[0]["event_type"] == "route"
+    assert rows[0]["payload"]["picked"] == ["a"]
+    con.close()

package/python/tests/test_npm_pkg_version.py

@@ -0,0 +1,21 @@
+"""published_package_version resolves package/package.json semver."""
+from __future__ import annotations
+
+from app.npm_pkg_version import NPM_PACKAGE_NAME, clear_version_cache_for_tests, published_package_version
+
+
+def test_published_package_version_matches_repo_package_json(monkeypatch) -> None:
+    monkeypatch.delenv("SKILLFORGE_MCP_SERVER_VERSION", raising=False)
+    clear_version_cache_for_tests()
+    v = published_package_version()
+    assert v and len(v.split(".")) == 3
+
+
+def test_published_package_version_env_override(monkeypatch) -> None:
+    monkeypatch.setenv("SKILLFORGE_MCP_SERVER_VERSION", "9.8.7-test")
+    clear_version_cache_for_tests()
+    assert published_package_version() == "9.8.7-test"
+
+
+def test_skillforge_package_name_constant() -> None:
+    assert "skillforge" in NPM_PACKAGE_NAME

package/python/tests/test_pick_diversify.py

@@ -0,0 +1,47 @@
+"""Tests for SKILLFORGE_PICK_DIVERSIFY trimming."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pytest
+
+
+@dataclass
+class _Sk:
+    name: str
+    source: str
+
+
+def test_diversify_disabled_by_default(monkeypatch) -> None:
+    monkeypatch.delenv("SKILLFORGE_PICK_DIVERSIFY", raising=False)
+    from app.pick_diversify import diversify_picked_names
+
+    by = {"a": _Sk("a", "bundled"), "b": _Sk("b", "bundled")}
+    out, meta = diversify_picked_names(["a", "b", "c"], by)
+    assert out == ["a", "b", "c"]
+    assert meta["applied"] is False
+
+
+def test_diversify_caps_per_source(monkeypatch) -> None:
+    monkeypatch.setenv("SKILLFORGE_PICK_DIVERSIFY", "1")
+    monkeypatch.setenv("SKILLFORGE_PICK_MAX_PER_SOURCE", "2")
+    from app.pick_diversify import diversify_picked_names
+
+    by = {f"s{i}": _Sk(f"s{i}", "bundled") for i in range(5)}
+    names = ["s0", "s1", "s2", "s3"]
+    out, meta = diversify_picked_names(names, by)
+    assert out == ["s0", "s1"]
+    assert meta["dropped"] == ["s2", "s3"]
+    assert meta["applied"] is True
+
+
+@pytest.mark.parametrize("truthy", ["1", "true", "yes"])
+def test_diversify_env_truthy(monkeypatch, truthy) -> None:
+    monkeypatch.setenv("SKILLFORGE_PICK_DIVERSIFY", truthy)
+    monkeypatch.setenv("SKILLFORGE_PICK_MAX_PER_SOURCE", "1")
+    from app.pick_diversify import diversify_picked_names
+
+    by = {"x": _Sk("x", "user"), "y": _Sk("y", "user")}
+    out, meta = diversify_picked_names(["x", "y"], by)
+    assert out == ["x"]
+    assert "y" in meta["dropped"]

package/python/tests/test_replay_cli.py

@@ -0,0 +1,31 @@
+"""Replay CLI row helpers."""
+
+from __future__ import annotations
+
+import sqlite3
+
+from app.replay_cli import _replay_rows
+
+
+def test_replay_filters_session(tmp_path) -> None:
+    db = tmp_path / "t.db"
+    con = sqlite3.connect(str(db))
+    con.execute(
+        """CREATE TABLE events (
+            id TEXT PRIMARY KEY, ts REAL, user_id TEXT, session_id TEXT, event_type TEXT, payload TEXT
+        )"""
+    )
+    con.execute(
+        "INSERT INTO events VALUES (?,?,?,?,?,?)",
+        ("1", 1.0, "u", "sess-a", "route", "{}"),
+    )
+    con.execute(
+        "INSERT INTO events VALUES (?,?,?,?,?,?)",
+        ("2", 2.0, "u", "sess-b", "route", "{}"),
+    )
+    con.commit()
+    rows = _replay_rows(con, session_id="sess-a", user_id="u", newest_first_snapshot=False, limit=50)
+    con.close()
+    assert len(rows) == 1
+    assert rows[0][2] == "route"
+