ida-code 0.2.1__tar.gz → 0.2.2__tar.gz

{ida_code-0.2.1 → ida_code-0.2.2}/CHANGELOG.md

@@ -4,7 +4,20 @@ All notable changes to this project will be documented in this file.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.2.2] - 2026-05-07
+
+### Added
+
+- **End-to-end regression test** — `tests/test_e2e.py` opens a real binary through fastmcp's in-process `Client` + `FastMCPTransport`, asserting the call returns within 15s. Catches future regressions that route idalib off the main thread (which would hang). Auto-skips when idalib isn't available.
+
+### Changed
+
+- **Pin fastmcp back to `>=2.0,<3`** — v3 dispatches sync tool functions to `anyio.to_thread.run_sync`, but idalib hangs indefinitely when called from a non-main thread, so every idalib-touching tool wedged. v2 runs sync tools on the main thread and works in 0.7s on the same call. Reverts the v2→v3 bump from 0.2.1.
+- **`open_database` refuses paths with unpacked fragments present** — if `.id0`/`.id1`/`.id2`/`.nam`/`.til` files exist for the target and `overwrite=False`, raise a clear `ToolError` listing them instead of letting idalib return an opaque `-1`. The message warns that the fragments may belong to another active IDA instance and only suggests `overwrite=True` if nothing else owns them.
+
+### Fixed
+
+- **`open_database` overwrite cleans up unpacked fragments** — `overwrite=True` now also deletes `.id0`, `.id1`, `.id2`, `.nam`, and `.til` files, not just `.i64`/`.idb`. A failed open could leave these partial fragments behind, after which every subsequent attempt would fail immediately with a generic `-1` because IDA refused to overwrite the half-written unpacked database.
 
 ## [0.2.1] - 2026-05-05
 

{ida_code-0.2.1 → ida_code-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ida-code
-Version: 0.2.1
+Version: 0.2.2
 Summary: MCP server for AI-assisted IDAPython scripting via idalib
 Project-URL: Homepage, https://github.com/Dil4rd/ida-code
 Project-URL: Repository, https://github.com/Dil4rd/ida-code
@@ -21,7 +21,7 @@ Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Disassemblers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
-Requires-Dist: fastmcp<4,>=3.0
+Requires-Dist: fastmcp<3,>=2.0
 Requires-Dist: lief>=0.15
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'
@@ -156,6 +156,10 @@ uv sync --extra dev
 uv run pytest
 ```
 
+## Known issues
+
+See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for caveats and workarounds (e.g. why we pin `fastmcp<3`).
+
 The test suite covers the executor, doc/example search, comments, snapshots, structures, undo, variables, and Mach-O parsing. Tests that need idalib are skipped if it's not available.
 
 ## Credits

{ida_code-0.2.1 → ida_code-0.2.2}/README.md

@@ -127,6 +127,10 @@ uv sync --extra dev
 uv run pytest
 ```
 
+## Known issues
+
+See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for caveats and workarounds (e.g. why we pin `fastmcp<3`).
+
 The test suite covers the executor, doc/example search, comments, snapshots, structures, undo, variables, and Mach-O parsing. Tests that need idalib are skipped if it's not available.
 
 ## Credits

{ida_code-0.2.1 → ida_code-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ida-code"
-version = "0.2.1"
+version = "0.2.2"
 description = "MCP server for AI-assisted IDAPython scripting via idalib"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -20,7 +20,7 @@ classifiers = [
     "Topic :: Software Development :: Disassemblers",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-dependencies = ["fastmcp>=3.0,<4", "lief>=0.15"]
+dependencies = ["fastmcp>=2.0,<3", "lief>=0.15"]
 
 [project.urls]
 Homepage = "https://github.com/Dil4rd/ida-code"

{ida_code-0.2.1 → ida_code-0.2.2}/src/ida_code/server.py

@@ -66,8 +66,9 @@ def open_database(
     Returns summary info (architecture, segments, entry points, function count).
     If a database is already open, it is closed first.
 
-    Set overwrite=True to delete any existing .i64/.idb database and force
-    a fresh analysis from the original binary.
+    Set overwrite=True to delete any existing .i64/.idb database (and any
+    unpacked .id0/.id1/.id2/.nam/.til fragments left by a failed open)
+    and force a fresh analysis from the original binary.
 
     *timeout* limits auto-analysis wait time in seconds (default 0 = unlimited).
     When the timeout expires the database stays open with partial analysis

{ida_code-0.2.1 → ida_code-0.2.2}/src/ida_code/session.py

@@ -149,6 +149,17 @@ def open(
 
     if overwrite:
         _remove_existing_databases(open_path)
+    else:
+        fragments = _list_unpacked_fragments(open_path)
+        if fragments:
+            raise ToolError(
+                f"Unpacked database fragments exist: {fragments}. "
+                f"This usually means another IDA instance has this database "
+                f"open, or a previous open failed and left them behind. "
+                f"If no other IDA process is using this database, re-call "
+                f"with overwrite=True to clean them up — but doing so while "
+                f"another IDA has it open will destroy that session's work."
+            )
 
     use_polling = auto_analysis and timeout > 0
     run_auto = auto_analysis and not use_polling
@@ -263,11 +274,37 @@ def _collect_summary(path: str) -> dict:
     }
 
 
+_DB_EXTENSIONS = (".i64", ".idb", ".id0", ".id1", ".id2", ".nam", ".til")
+_UNPACKED_FRAGMENT_EXTS = (".id0", ".id1", ".id2", ".nam", ".til")
+
+
+def _list_unpacked_fragments(path: str) -> list[str]:
+    """Return any unpacked database fragments existing for *path*.
+
+    These exist while a database is open in IDA, and can also be left
+    behind when a previous open failed mid-unpacking. Their presence
+    makes ``idapro.open_database`` refuse the path with rc=-1.
+    """
+    from pathlib import Path
+    p = Path(path)
+    found = []
+    for ext in _UNPACKED_FRAGMENT_EXTS:
+        for candidate in {p.with_suffix(ext), Path(str(p) + ext)}:
+            if candidate.is_file():
+                found.append(str(candidate))
+    return found
+
+
 def _remove_existing_databases(path: str) -> None:
-    """Remove existing IDA database files so a fresh analysis starts."""
+    """Remove existing IDA database files and unpacked fragments.
+
+    Includes the unpacked fragment extensions (.id0/.id1/.id2/.nam/.til) so
+    that a half-written database from a previously failed open does not
+    block the next attempt.
+    """
     from pathlib import Path
     p = Path(path)
-    for ext in (".i64", ".idb"):
+    for ext in _DB_EXTENSIONS:
         for candidate in {p.with_suffix(ext), Path(str(p) + ext)}:
             if candidate.is_file():
                 candidate.unlink()

ida_code-0.2.2/tests/test_e2e.py

@@ -0,0 +1,79 @@
+"""End-to-end test exercising the MCP server through fastmcp's in-process
+client. Regression guard: any change that pushes idalib calls onto a
+worker thread (e.g. a future fastmcp version doing async-hygiene
+dispatch of sync tools) hangs idalib and trips the asyncio timeout
+below — failing fast instead of hanging CI indefinitely.
+
+Auto-skipped when idalib isn't loadable.
+"""
+
+import asyncio
+import shutil
+import time
+from pathlib import Path
+
+import pytest
+
+# Importing ida_code.session has the side effect of inserting idalib's
+# python dir into sys.path and `import idapro`. If idalib isn't present
+# the import fails — skip the whole module instead of erroring.
+try:
+    from ida_code import session
+    from ida_code.server import mcp
+except ImportError as exc:
+    pytest.skip(f"idalib not available: {exc}", allow_module_level=True)
+
+from fastmcp.client import Client  # noqa: E402
+from fastmcp.client.transports import FastMCPTransport  # noqa: E402
+
+
+def _venv_binary() -> Path:
+    """A small native extension shipped in the venv — analyzes in ~2s cold."""
+    import charset_normalizer.md as _md
+    return Path(_md.__file__)
+
+
+@pytest.fixture
+def target(tmp_path):
+    src = _venv_binary()
+    if not src.is_file():
+        pytest.skip(f"venv binary not found: {src}")
+    dst = tmp_path / "target.so"
+    shutil.copy(src, dst)
+    yield str(dst)
+    # Make sure no database stays open across tests.
+    if session.get_state() == session.State.DATABASE_OPEN:
+        try:
+            session.close()
+        except Exception:
+            pass
+
+
+async def _open_and_close(target_path: str) -> float:
+    async with Client(FastMCPTransport(mcp)) as client:
+        t0 = time.monotonic()
+        r = await asyncio.wait_for(
+            client.call_tool("open_database", {"path": target_path}),
+            timeout=30,
+        )
+        elapsed = time.monotonic() - t0
+
+        data = r.data if hasattr(r, "data") else r
+        assert isinstance(data, dict), f"unexpected result type: {type(data)}"
+        assert data.get("function_count", 0) > 0, f"no functions analyzed: {data}"
+
+        await asyncio.wait_for(
+            client.call_tool("close_database", {}),
+            timeout=10,
+        )
+    return elapsed
+
+
+def test_open_database_via_in_process_client(target):
+    """Open a real binary through the MCP tool surface and verify it returns
+    a populated summary in well under the timeout. A future regression that
+    routes idalib off the main thread would hit the 30s ``wait_for``."""
+    elapsed = asyncio.run(_open_and_close(target))
+    # Generous bound: 16KB binary, ~2s cold standalone. Anything near the
+    # 30s ceiling means dispatch is wrong, not just slow.
+    assert elapsed < 15, f"open took {elapsed:.1f}s — possible thread regression"

ida_code-0.2.2/tests/test_session.py

@@ -0,0 +1,125 @@
+"""Unit tests for ida_code.session.
+
+These tests work without idalib — they mock the session module globals
+and os.path.isfile to test the file-existence guard logic.
+"""
+
+import os
+import tempfile
+from unittest.mock import patch
+
+import pytest
+from fastmcp.exceptions import ToolError
+
+from ida_code import session
+
+
+class TestRequireOpen:
+    def setup_method(self):
+        """Save and restore session module globals around each test."""
+        self._orig_state = session._state
+        self._orig_db_file_path = session._db_file_path
+        self._orig_orphaned = session._orphaned
+
+    def teardown_method(self):
+        session._state = self._orig_state
+        session._db_file_path = self._orig_db_file_path
+        session._orphaned = self._orig_orphaned
+
+    def test_raises_when_no_database(self):
+        session._state = session.State.NO_DATABASE
+        with pytest.raises(ToolError, match="No database is open"):
+            session.require_open()
+
+    @patch("ida_code.session.os.path.isfile", return_value=True)
+    def test_passes_when_open_and_file_exists(self, mock_isfile):
+        session._state = session.State.DATABASE_OPEN
+        session._db_file_path = "/tmp/test.i64"
+        session.require_open()  # should not raise
+        mock_isfile.assert_called_once_with("/tmp/test.i64")
+
+    @patch("ida_code.session.os.path.isfile", return_value=False)
+    @patch("ida_code.executor.reset")
+    def test_resets_state_when_file_missing(self, mock_reset, mock_isfile):
+        session._state = session.State.DATABASE_OPEN
+        session._db_file_path = "/tmp/gone.i64"
+        session._orphaned = False
+
+        with pytest.raises(ToolError, match="moved or deleted"):
+            session.require_open()
+
+        assert session._state == session.State.NO_DATABASE
+        assert session._orphaned is True
+        assert session._db_file_path is None
+        mock_reset.assert_called_once()
+
+    def test_passes_when_db_file_path_is_none(self):
+        """Graceful degradation: if _db_file_path was never set, skip the
+        file check and rely only on the state enum."""
+        session._state = session.State.DATABASE_OPEN
+        session._db_file_path = None
+        session.require_open()  # should not raise
+
+
+class TestUnpackedFragmentPrecheck:
+    """`open()` must refuse paths with leftover unpacked fragments unless
+    overwrite=True — calling idapro on such a path returns rc=-1 and can
+    leave idalib's internal state corrupted."""
+
+    def setup_method(self):
+        self._orig_state = session._state
+
+    def teardown_method(self):
+        session._state = self._orig_state
+
+    def test_lists_unpacked_fragments(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            binary = os.path.join(tmp, "x.so")
+            open(binary, "w").close()
+            for ext in (".id0", ".id1", ".nam"):
+                open(binary + ext, "w").close()
+            found = session._list_unpacked_fragments(binary)
+            assert sorted(found) == sorted(binary + ext for ext in (".id0", ".id1", ".nam"))
+
+    def test_returns_empty_for_clean_path(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            binary = os.path.join(tmp, "x.so")
+            open(binary, "w").close()
+            assert session._list_unpacked_fragments(binary) == []
+
+    def test_does_not_flag_packed_databases(self):
+        """A `.i64` next to the binary is a valid warm cache, not a fragment."""
+        with tempfile.TemporaryDirectory() as tmp:
+            binary = os.path.join(tmp, "x.so")
+            open(binary, "w").close()
+            open(binary + ".i64", "w").close()
+            assert session._list_unpacked_fragments(binary) == []
+
+    def test_open_raises_with_fragments_no_overwrite(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            binary = os.path.join(tmp, "x.so")
+            open(binary, "w").close()
+            open(binary + ".id0", "w").close()
+
+            session._state = session.State.NO_DATABASE
+            with patch("ida_code.session.idapro.open_database") as mock_open:
+                with pytest.raises(ToolError, match="Unpacked database fragments"):
+                    session.open(binary, auto_analysis=False)
+            mock_open.assert_not_called()  # idalib must not be invoked
+
+    def test_open_proceeds_with_fragments_when_overwrite_true(self):
+        """overwrite=True clears fragments and proceeds with the open."""
+        with tempfile.TemporaryDirectory() as tmp:
+            binary = os.path.join(tmp, "x.so")
+            open(binary, "w").close()
+            open(binary + ".id0", "w").close()
+
+            session._state = session.State.NO_DATABASE
+            with patch("ida_code.session.idapro.open_database", return_value=0), \
+                 patch("ida_code.session._collect_summary", return_value={"path": binary}), \
+                 patch("ida_code.executor.reset"):
+                # Should not raise — fragment is cleaned up before open.
+                session.open(binary, auto_analysis=False, overwrite=True)
+            # Fragment file should have been removed.
+            assert not os.path.isfile(binary + ".id0")
+            session._state = session.State.NO_DATABASE  # reset for teardown

ida_code-0.2.1/tests/test_session.py

@@ -1,59 +0,0 @@
-"""Unit tests for ida_code.session.require_open().
-
-These tests work without idalib — they mock the session module globals
-and os.path.isfile to test the file-existence guard logic.
-"""
-
-from unittest.mock import patch
-
-import pytest
-from fastmcp.exceptions import ToolError
-
-from ida_code import session
-
-
-class TestRequireOpen:
-    def setup_method(self):
-        """Save and restore session module globals around each test."""
-        self._orig_state = session._state
-        self._orig_db_file_path = session._db_file_path
-        self._orig_orphaned = session._orphaned
-
-    def teardown_method(self):
-        session._state = self._orig_state
-        session._db_file_path = self._orig_db_file_path
-        session._orphaned = self._orig_orphaned
-
-    def test_raises_when_no_database(self):
-        session._state = session.State.NO_DATABASE
-        with pytest.raises(ToolError, match="No database is open"):
-            session.require_open()
-
-    @patch("ida_code.session.os.path.isfile", return_value=True)
-    def test_passes_when_open_and_file_exists(self, mock_isfile):
-        session._state = session.State.DATABASE_OPEN
-        session._db_file_path = "/tmp/test.i64"
-        session.require_open()  # should not raise
-        mock_isfile.assert_called_once_with("/tmp/test.i64")
-
-    @patch("ida_code.session.os.path.isfile", return_value=False)
-    @patch("ida_code.executor.reset")
-    def test_resets_state_when_file_missing(self, mock_reset, mock_isfile):
-        session._state = session.State.DATABASE_OPEN
-        session._db_file_path = "/tmp/gone.i64"
-        session._orphaned = False
-
-        with pytest.raises(ToolError, match="moved or deleted"):
-            session.require_open()
-
-        assert session._state == session.State.NO_DATABASE
-        assert session._orphaned is True
-        assert session._db_file_path is None
-        mock_reset.assert_called_once()
-
-    def test_passes_when_db_file_path_is_none(self):
-        """Graceful degradation: if _db_file_path was never set, skip the
-        file check and rely only on the state enum."""
-        session._state = session.State.DATABASE_OPEN
-        session._db_file_path = None
-        session.require_open()  # should not raise