sourcecode 1.31.28__tar.gz → 1.31.29__tar.gz

{sourcecode-1.31.28 → sourcecode-1.31.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.31.28
+Version: 1.31.29
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -225,7 +225,7 @@ Description-Content-Type: text/markdown
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.28-blue)
+![Version](https://img.shields.io/badge/version-1.31.29-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -263,7 +263,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.28
+# sourcecode 1.31.29
 ```
 
 ---

{sourcecode-1.31.28 → sourcecode-1.31.29}/README.md

@@ -2,7 +2,7 @@
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.28-blue)
+![Version](https://img.shields.io/badge/version-1.31.29-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -40,7 +40,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.28
+# sourcecode 1.31.29
 ```
 
 ---

{sourcecode-1.31.28 → sourcecode-1.31.29}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.31.28"
+version = "1.31.29"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.31.28 → sourcecode-1.31.29}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.31.28"
+__version__ = "1.31.29"

{sourcecode-1.31.28 → sourcecode-1.31.29}/src/sourcecode/cli.py

@@ -1952,6 +1952,10 @@ def main(
             if _copy_to_clipboard(content):
                 typer.echo("✓ copied to clipboard", err=True)
 
+    # 8. One-time MCP setup nudge (stderr only — does not affect exit code or stdout)
+    from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
+    _nudge()
+
 
 # ── prepare-context output helpers ────────────────────────────────────────────
 
@@ -2554,6 +2558,9 @@ def prepare_context_cmd(
             if _copy_to_clipboard(_pc_content):
                 typer.echo("✓ copied to clipboard", err=True)
 
+    from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
+    _nudge()
+
 
 # ── Telemetry commands ────────────────────────────────────────────────────────
 
@@ -2899,6 +2906,9 @@ def impact_cmd(
     if result.get("resolution") == "not_found":
         raise typer.Exit(code=1)
 
+    from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
+    _nudge()
+
 
 # ── endpoints ─────────────────────────────────────────────────────────────────
 
@@ -2969,6 +2979,9 @@ def endpoints_cmd(
             if _copy_to_clipboard(output):
                 typer.echo("✓ copied to clipboard", err=True)
 
+    from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
+    _nudge()
+
 
 # ── Enterprise Workflow Commands ──────────────────────────────────────────────
 #
@@ -3574,6 +3587,10 @@ def mcp_init(
     typer.echo("")
     typer.echo("  Remove:  sourcecode mcp remove")
 
+    # Clear nudge flag: next run finds is_installed=True → no nudge.
+    from sourcecode.mcp_nudge import clear_nudge_flag as _clear_nudge
+    _clear_nudge()
+
 
 @mcp_app.command("status")
 def mcp_status() -> None:

sourcecode-1.31.29/src/sourcecode/mcp_nudge.py

@@ -0,0 +1,84 @@
+"""MCP setup nudge — one-time stderr hint after successful analysis commands.
+
+Fires when:
+  1. At least one known MCP client (Claude Desktop, Cursor) is installed
+  2. sourcecode is NOT yet registered in that client's config
+  3. The nudge hasn't been shown this session (~/.sourcecode/nudge_shown flag)
+
+Cleared by: a successful `sourcecode mcp init` (deletes the flag so the
+post-init detection finds is_installed=True and never nudges again).
+
+Side effects: writes only to stderr — stdout (JSON/YAML output) is untouched.
+Exit code of the calling command is unaffected.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Stable path used as a session-level "already shown" sentinel.
+_FLAG: Path = Path.home() / ".sourcecode" / "nudge_shown"
+
+_MSG = (
+    "→ Claude Desktop detected. "
+    "Run `sourcecode mcp init` to enable agent integration.\n"
+)
+
+# Module-level imports so names are patchable in tests.
+# Falls back to no-op stubs if onboarding package is unavailable.
+try:
+    from sourcecode.mcp.onboarding.detector import detect_clients  # noqa: PLC0415
+    from sourcecode.mcp.onboarding.applier import is_installed, read_config  # noqa: PLC0415
+    _IMPORTS_OK = True
+except Exception:  # pragma: no cover
+    _IMPORTS_OK = False
+
+    def detect_clients() -> list:  # type: ignore[misc]
+        return []
+
+    def is_installed(config: dict) -> bool:  # type: ignore[misc]
+        return False
+
+    def read_config(path: Path) -> dict:  # type: ignore[misc]
+        return {}
+
+
+def nudge_mcp_if_needed() -> None:
+    """Print MCP setup nudge to stderr at most once (until mcp init succeeds)."""
+    # Fast path: already shown this session.
+    if _FLAG.exists():
+        return
+
+    try:
+        clients = detect_clients()
+    except Exception:  # pragma: no cover
+        return
+
+    needs_nudge = any(
+        c.app_installed and not is_installed(read_config(c.config_path))
+        for c in clients
+    )
+
+    if not needs_nudge:
+        return
+
+    # Write nudge and persist flag.
+    sys.stderr.write(_MSG)
+    sys.stderr.flush()
+    try:
+        _FLAG.parent.mkdir(parents=True, exist_ok=True)
+        _FLAG.touch()
+    except OSError:
+        pass  # Non-fatal: nudge will fire again next run, which is acceptable.
+
+
+def clear_nudge_flag() -> None:
+    """Delete the session flag so post-mcp-init runs don't re-show the nudge.
+
+    Called by `mcp init` after a successful installation.  On the next run,
+    detection finds is_installed=True → needs_nudge=False → no nudge shown.
+    """
+    try:
+        _FLAG.unlink(missing_ok=True)
+    except OSError:
+        pass

sourcecode-1.31.29/tests/test_mcp_nudge.py

@@ -0,0 +1,153 @@
+"""Tests for sourcecode.mcp_nudge — one-time MCP setup nudge."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import sourcecode.mcp_nudge as nudge_mod
+from sourcecode.mcp_nudge import nudge_mcp_if_needed, clear_nudge_flag
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _make_client(app_installed: bool, config_path: Path) -> MagicMock:
+    client = MagicMock()
+    client.app_installed = app_installed
+    client.config_path = config_path
+    return client
+
+
+# ── nudge_mcp_if_needed ───────────────────────────────────────────────────────
+
+class TestNudgeMcpIfNeeded:
+    """Core nudge logic — isolation via tmp_path flag dir."""
+
+    def _run(self, flag_path: Path, clients, is_installed_val: bool, capsys) -> str:
+        """Invoke nudge_mcp_if_needed with patched flag, clients and is_installed."""
+        with (
+            patch.object(nudge_mod, "_FLAG", flag_path),
+            patch("sourcecode.mcp_nudge.detect_clients", return_value=clients),
+            patch("sourcecode.mcp_nudge.is_installed", return_value=is_installed_val),
+            patch("sourcecode.mcp_nudge.read_config", return_value={}),
+        ):
+            nudge_mcp_if_needed()
+        return capsys.readouterr().err
+
+    def test_nudge_shown_when_desktop_installed_not_configured(self, tmp_path, capsys):
+        """Client installed, not in config → nudge printed."""
+        flag = tmp_path / "nudge_shown"
+        client = _make_client(app_installed=True, config_path=tmp_path / "config.json")
+        stderr = self._run(flag, [client], is_installed_val=False, capsys=capsys)
+        assert "sourcecode mcp init" in stderr
+        assert flag.exists(), "Flag must be created after nudge"
+
+    def test_no_nudge_when_already_configured(self, tmp_path, capsys):
+        """Client installed AND already in config → no nudge."""
+        flag = tmp_path / "nudge_shown"
+        client = _make_client(app_installed=True, config_path=tmp_path / "config.json")
+        stderr = self._run(flag, [client], is_installed_val=True, capsys=capsys)
+        assert stderr == ""
+        assert not flag.exists()
+
+    def test_no_nudge_when_client_not_installed(self, tmp_path, capsys):
+        """Client NOT installed → no nudge even if config absent."""
+        flag = tmp_path / "nudge_shown"
+        client = _make_client(app_installed=False, config_path=tmp_path / "config.json")
+        stderr = self._run(flag, [client], is_installed_val=False, capsys=capsys)
+        assert stderr == ""
+        assert not flag.exists()
+
+    def test_no_nudge_when_flag_exists(self, tmp_path, capsys):
+        """Flag already present → no nudge (second run in same session)."""
+        flag = tmp_path / "nudge_shown"
+        flag.touch()
+        client = _make_client(app_installed=True, config_path=tmp_path / "config.json")
+        stderr = self._run(flag, [client], is_installed_val=False, capsys=capsys)
+        assert stderr == ""
+
+    def test_no_nudge_when_no_clients(self, tmp_path, capsys):
+        """No clients detected → no nudge."""
+        flag = tmp_path / "nudge_shown"
+        stderr = self._run(flag, [], is_installed_val=False, capsys=capsys)
+        assert stderr == ""
+        assert not flag.exists()
+
+    def test_second_call_no_repeat(self, tmp_path, capsys):
+        """Nudge fires once; second call (flag now exists) is silent."""
+        flag = tmp_path / "nudge_shown"
+        client = _make_client(app_installed=True, config_path=tmp_path / "config.json")
+
+        with (
+            patch.object(nudge_mod, "_FLAG", flag),
+            patch("sourcecode.mcp_nudge.detect_clients", return_value=[client]),
+            patch("sourcecode.mcp_nudge.is_installed", return_value=False),
+            patch("sourcecode.mcp_nudge.read_config", return_value={}),
+        ):
+            nudge_mcp_if_needed()
+            capsys.readouterr()  # consume first write
+            nudge_mcp_if_needed()
+
+        second_stderr = capsys.readouterr().err
+        assert second_stderr == ""
+
+    def test_nudge_message_exact_text(self, tmp_path, capsys):
+        """Message matches spec exactly."""
+        flag = tmp_path / "nudge_shown"
+        client = _make_client(app_installed=True, config_path=tmp_path / "config.json")
+        stderr = self._run(flag, [client], is_installed_val=False, capsys=capsys)
+        assert stderr == (
+            "→ Claude Desktop detected. "
+            "Run `sourcecode mcp init` to enable agent integration.\n"
+        )
+
+    def test_import_error_is_silent(self, tmp_path, capsys):
+        """If onboarding modules can't be imported, nudge fails silently."""
+        flag = tmp_path / "nudge_shown"
+        with (
+            patch.object(nudge_mod, "_FLAG", flag),
+            patch.dict("sys.modules", {
+                "sourcecode.mcp.onboarding.detector": None,  # type: ignore[dict-item]
+                "sourcecode.mcp.onboarding.applier": None,   # type: ignore[dict-item]
+            }),
+        ):
+            nudge_mcp_if_needed()  # must not raise
+        assert capsys.readouterr().err == ""
+
+
+# ── clear_nudge_flag ──────────────────────────────────────────────────────────
+
+class TestClearNudgeFlag:
+    def test_clears_existing_flag(self, tmp_path):
+        flag = tmp_path / "nudge_shown"
+        flag.touch()
+        with patch.object(nudge_mod, "_FLAG", flag):
+            clear_nudge_flag()
+        assert not flag.exists()
+
+    def test_noop_when_flag_absent(self, tmp_path):
+        flag = tmp_path / "nudge_shown"
+        with patch.object(nudge_mod, "_FLAG", flag):
+            clear_nudge_flag()  # must not raise
+        assert not flag.exists()
+
+    def test_after_clear_nudge_fires_again_if_not_configured(self, tmp_path, capsys):
+        """After mcp init clears flag, if somehow not configured, nudge re-fires."""
+        flag = tmp_path / "nudge_shown"
+        flag.touch()
+        client = _make_client(app_installed=True, config_path=tmp_path / "config.json")
+
+        with patch.object(nudge_mod, "_FLAG", flag):
+            clear_nudge_flag()
+
+        with (
+            patch.object(nudge_mod, "_FLAG", flag),
+            patch("sourcecode.mcp_nudge.detect_clients", return_value=[client]),
+            patch("sourcecode.mcp_nudge.is_installed", return_value=False),
+            patch("sourcecode.mcp_nudge.read_config", return_value={}),
+        ):
+            nudge_mcp_if_needed()
+
+        assert "mcp init" in capsys.readouterr().err