eljay-ai 1.1.0

package/tests/test_universal.py

@@ -0,0 +1,458 @@
+"""Tests for ElJay AI universal-assistant components.
+
+Run from the project root:
+    python tests/test_universal.py
+
+These are deterministic and do NOT require Ollama or network access.
+"""
+
+import os
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+class HardwareTests(unittest.TestCase):
+    def test_detect_hardware_returns_hardware_info(self):
+        from agent.hardware import detect_hardware
+        hw = detect_hardware()
+        self.assertIsNotNone(hw)
+        self.assertTrue(hasattr(hw, "os"))
+        self.assertTrue(hasattr(hw, "cpu_cores"))
+        self.assertTrue(hasattr(hw, "ram_gb"))
+        self.assertTrue(hasattr(hw, "can_code"))
+        self.assertTrue(hasattr(hw, "can_image"))
+        self.assertTrue(hasattr(hw, "can_video"))
+
+    def test_summarize_hardware_returns_string(self):
+        from agent.hardware import detect_hardware, summarize_hardware
+        hw = detect_hardware()
+        s = summarize_hardware(hw)
+        self.assertIsInstance(s, str)
+        self.assertTrue(len(s) > 0)
+
+
+class HardwareVramTests(unittest.TestCase):
+    def test_hardware_has_vram_available_field(self):
+        from agent.hardware import detect_hardware
+        hw = detect_hardware()
+        self.assertTrue(hasattr(hw, "vram_available_gb"))
+        self.assertTrue(hasattr(hw, "vram_total_gb"))
+
+    def test_summarize_hardware_handles_no_gpu(self):
+        from agent.hardware import summarize_hardware, HardwareInfo
+        hw = HardwareInfo(gpu="none", vram_total_gb=0.0, vram_available_gb=0.0)
+        s = summarize_hardware(hw)
+        self.assertIn("none", s.lower())
+
+    def test_recommended_image_mode_returns_string(self):
+        from agent.hardware import HardwareInfo
+        hw = HardwareInfo()
+        s = hw.recommended_image_mode()
+        self.assertIsInstance(s, str)
+
+    def test_recommended_video_mode_returns_string(self):
+        from agent.hardware import HardwareInfo
+        hw = HardwareInfo()
+        s = hw.recommended_video_mode()
+        self.assertIsInstance(s, str)
+
+
+class RouterTests(unittest.TestCase):
+    def test_router_importable(self):
+        from agent.router import AgentRouter
+        self.assertTrue(callable(AgentRouter))
+
+    def test_router_can_be_constructed(self):
+        from agent.router import AgentRouter
+        from agent.skills import Skills
+        from agent.knowledge import KnowledgeBase
+        root = Path(__file__).resolve().parent.parent
+        skills = Skills(str(root))
+        knowledge = KnowledgeBase(str(root), str(root))
+        router = AgentRouter(skills=skills, knowledge=knowledge)
+        self.assertIsNotNone(router)
+
+    def test_router_len_returns_agent_count(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        self.assertGreater(len(router), 0)
+
+    def test_router_registry_is_list(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        self.assertIsInstance(router.registry, list)
+
+    def test_route_returns_agent_definition(self):
+        from agent.router import AgentRouter
+        from agent.agents import AgentDefinition
+        router = AgentRouter()
+        # Without provider availability checks, route based on keywords.
+        from agent.agents import route_request
+        agent = route_request("write some code", None)
+        self.assertIsInstance(agent, AgentDefinition)
+
+    def test_route_image_via_route_request(self):
+        from agent.agents import route_request
+        agent = route_request("create an image of a cowboy", None)
+        self.assertEqual(agent.name, "image")
+
+    def test_route_video_via_route_request(self):
+        from agent.agents import route_request
+        agent = route_request("make a cinematic video", None)
+        self.assertEqual(agent.name, "video")
+
+    def test_route_research_via_route_request(self):
+        from agent.agents import route_request
+        agent = route_request("research the latest Laravel", None)
+        self.assertEqual(agent.name, "research")
+
+    def test_route_coding_via_route_request(self):
+        from agent.agents import route_request
+        agent = route_request("fix my React error", None)
+        self.assertEqual(agent.name, "coding")
+
+    def test_route_knowledge_via_route_request(self):
+        from agent.agents import route_request
+        agent = route_request("explain quantum computing", None)
+        # Knowledge or main fallback
+        self.assertIn(agent.name, ("knowledge", "main"))
+
+    def test_delegated_agent_for_returns_none_for_main(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        # route_request with provider availability may return main for "hello"
+        result = router.delegated_agent_for("hello")
+        self.assertTrue(result is None or hasattr(result, "name"))
+
+    def test_delegated_agent_for_returns_agent_for_specialist(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        # route_request with None providers bypasses availability check
+        from agent.agents import route_request
+        agent = route_request("create an image", None)
+        if agent.name == "image":
+            self.assertEqual(agent.name, "image")
+        else:
+            # If image provider unavailable, router.route may return main.
+            # But route_request with None should still match image.
+            self.assertEqual(agent.name, "image")
+
+    def test_agent_by_name(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        agent = router.agent_by_name("image")
+        self.assertIsNotNone(agent)
+        self.assertEqual(agent.name, "image")
+
+    def test_all_agents_returns_list(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        agents = router.all_agents()
+        self.assertIsInstance(agents, list)
+        self.assertGreater(len(agents), 0)
+
+    def test_provider_status_returns_dict(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        status = router.provider_status()
+        self.assertIsInstance(status, dict)
+
+    def test_inject_context_returns_string(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        from agent.agents import route_request
+        agent = route_request("coding help", None)
+        ctx = router.inject_context("coding help", agent)
+        self.assertIsInstance(ctx, str)
+
+    def test_route_falls_back_to_main_for_greeting(self):
+        from agent.agents import route_request
+        agent = route_request("hello world", None)
+        self.assertEqual(agent.name, "main")
+
+    def test_route_image_via_router_even_without_provider(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        agent = router.route("create an image of a cyberpunk city")
+        self.assertEqual(agent.name, "image")
+
+    def test_route_video_via_router_even_without_provider(self):
+        from agent.router import AgentRouter
+        router = AgentRouter()
+        agent = router.route("make a cinematic video")
+        self.assertEqual(agent.name, "video")
+
+
+class SkillsTests(unittest.TestCase):
+    def test_skills_importable(self):
+        from agent.skills import Skills
+        self.assertTrue(callable(Skills))
+
+    def test_skills_can_be_constructed(self):
+        from agent.skills import Skills
+        root = Path(__file__).resolve().parent.parent
+        skills = Skills(str(root))
+        self.assertIsNotNone(skills)
+
+    def test_skills_all_skills_returns_list(self):
+        from agent.skills import Skills
+        root = Path(__file__).resolve().parent.parent
+        skills = Skills(str(root))
+        self.assertIsInstance(skills.all_skills(), list)
+
+    def test_skills_has_summary(self):
+        from agent.skills import Skills
+        root = Path(__file__).resolve().parent.parent
+        skills = Skills(str(root))
+        s = skills.summary()
+        self.assertIsInstance(s, str)
+
+    def test_skills_relevant_to(self):
+        from agent.skills import Skills
+        root = Path(__file__).resolve().parent.parent
+        skills = Skills(str(root))
+        results = skills.relevant_to("debug")
+        self.assertIsInstance(results, list)
+
+    def test_skills_search(self):
+        from agent.skills import Skills
+        root = Path(__file__).resolve().parent.parent
+        skills = Skills(str(root))
+        results = skills.search("coding")
+        self.assertIsInstance(results, list)
+
+    def test_skills_directory_exists(self):
+        root = Path(__file__).resolve().parent.parent / "skills"
+        self.assertTrue(root.exists(), "skills/ directory should exist")
+
+    def test_skills_directory_has_content(self):
+        root = Path(__file__).resolve().parent.parent / "skills"
+        skills = list(root.rglob("*.md"))
+        self.assertGreater(len(skills), 0, "skills/ should contain .md files")
+
+
+class KnowledgeTests(unittest.TestCase):
+    def test_knowledge_importable(self):
+        from agent.knowledge import KnowledgeBase
+        self.assertTrue(callable(KnowledgeBase))
+
+    def test_knowledge_can_be_constructed(self):
+        from agent.knowledge import KnowledgeBase
+        root = str(Path(__file__).resolve().parent.parent)
+        kb = KnowledgeBase(root, root)
+        self.assertIsNotNone(kb)
+
+    def test_knowledge_load_global(self):
+        from agent.knowledge import KnowledgeBase
+        root = str(Path(__file__).resolve().parent.parent)
+        kb = KnowledgeBase(root, root)
+        entries = kb.entries()
+        self.assertIsInstance(entries, list)
+
+    def test_knowledge_has_summary(self):
+        from agent.knowledge import KnowledgeBase
+        root = str(Path(__file__).resolve().parent.parent)
+        kb = KnowledgeBase(root, root)
+        s = kb.summary()
+        self.assertIsInstance(s, str)
+
+    def test_knowledge_search_returns_list(self):
+        from agent.knowledge import KnowledgeBase
+        root = str(Path(__file__).resolve().parent.parent)
+        kb = KnowledgeBase(root, root)
+        results = kb.search("image")
+        self.assertIsInstance(results, list)
+
+    def test_knowledge_directory_exists(self):
+        root = Path(__file__).resolve().parent.parent / "knowledge"
+        self.assertTrue(root.exists(), "knowledge/ directory should exist")
+
+    def test_knowledge_add_and_search(self):
+        from agent.knowledge import KnowledgeBase
+        root = str(Path(__file__).resolve().parent.parent)
+        kb = KnowledgeBase(root, root)
+        kb.add_entry("test-category", "test-entry", "a test entry about Python", "Python is a programming language", project_local=False)
+        results = kb.search("Python")
+        self.assertGreater(len(results), 0)
+
+
+class AgentsRegistryTests(unittest.TestCase):
+    def test_list_agents_returns_all(self):
+        from agent.agents import list_agents
+        agents = list_agents()
+        self.assertGreaterEqual(len(agents), 6, "Should have at least 6 agent types")
+
+    def test_main_agent_present(self):
+        from agent.agents import get_agent
+        agent = get_agent("main")
+        self.assertIsNotNone(agent)
+        self.assertEqual(agent.name, "main")
+
+    def test_coding_agent_present(self):
+        from agent.agents import get_agent
+        agent = get_agent("coding")
+        self.assertIsNotNone(agent)
+        self.assertEqual(agent.name, "coding")
+
+    def test_image_agent_present(self):
+        from agent.agents import get_agent
+        agent = get_agent("image")
+        self.assertIsNotNone(agent)
+        self.assertEqual(agent.name, "image")
+
+    def test_video_agent_present(self):
+        from agent.agents import get_agent
+        agent = get_agent("video")
+        self.assertIsNotNone(agent)
+        self.assertEqual(agent.name, "video")
+
+    def test_research_agent_present(self):
+        from agent.agents import get_agent
+        agent = get_agent("research")
+        self.assertIsNotNone(agent)
+        self.assertEqual(agent.name, "research")
+
+    def test_knowledge_agent_present(self):
+        from agent.agents import get_agent
+        agent = get_agent("knowledge")
+        self.assertIsNotNone(agent)
+        self.assertEqual(agent.name, "knowledge")
+
+    def test_route_request_returns_agent(self):
+        from agent.agents import route_request
+        agent = route_request("create an image", None)
+        self.assertEqual(agent.name, "image")
+
+    def test_route_request_fallback_to_main(self):
+        from agent.agents import route_request
+        agent = route_request("hello world", None)
+        self.assertEqual(agent.name, "main")
+
+    def test_route_request_coding_keywords(self):
+        from agent.agents import route_request
+        agent = route_request("fix my code", None)
+        self.assertEqual(agent.name, "coding")
+
+
+class ProvidersTests(unittest.TestCase):
+    def test_providers_importable(self):
+        from agent.providers import PROVIDERS
+        self.assertIsInstance(PROVIDERS, list)
+
+    def test_providers_has_required_types(self):
+        from agent.providers import PROVIDERS
+        names = [p.name for p in PROVIDERS]
+        self.assertIn("ollama", names)
+
+    def test_get_provider_capable_of_returns_provider(self):
+        from agent.providers import get_provider_capable_of
+        provider = get_provider_capable_of("text")
+        self.assertIsNotNone(provider)
+
+    def test_get_provider_capable_of_returns_none_for_missing(self):
+        from agent.providers import get_provider_capable_of
+        provider = get_provider_capable_of("nonexistent-capability")
+        self.assertIsNone(provider)
+
+    def test_image_provider_importable(self):
+        from agent.providers.image import ImageProvider
+        self.assertTrue(hasattr(ImageProvider, "status_string"))
+
+    def test_video_provider_importable(self):
+        from agent.providers.video import VideoProvider
+        self.assertTrue(hasattr(VideoProvider, "status_string"))
+
+    def test_web_search_provider_importable(self):
+        from agent.providers.web import WebSearchProvider
+        self.assertTrue(hasattr(WebSearchProvider, "status_string"))
+
+    def test_search_ddg_function_exists(self):
+        from agent.providers.web import search_ddg
+        self.assertTrue(callable(search_ddg))
+
+    def test_fetch_web_page_function_exists(self):
+        from agent.providers.web import fetch_web_page
+        self.assertTrue(callable(fetch_web_page))
+
+
+class ToolRegistryTests(unittest.TestCase):
+    def test_register_builtin_tools_callable(self):
+        from agent.builtin_tools import register_builtin_tools
+        self.assertTrue(callable(register_builtin_tools))
+
+    def test_tool_registry_has_tools(self):
+        from agent.tools import ToolRegistry
+        from agent.builtin_tools import register_builtin_tools
+        from agent.workspace import Workspace, find_project_root
+        from agent.memory import Memory
+        from pathlib import Path
+        ws = Workspace(find_project_root(Path.cwd()))
+        mem = Memory(ws)
+        registry = ToolRegistry()
+        register_builtin_tools(registry, ws, mem)
+        self.assertGreater(len(registry), 0)
+
+
+class CLITests(unittest.TestCase):
+    def test_eljay_has_main(self):
+        import eljay
+        self.assertTrue(callable(eljay.main))
+
+    def test_myagent_is_alias(self):
+        import myagent
+        self.assertTrue(callable(myagent.main))
+
+    def test_build_registry_callable(self):
+        import eljay
+        self.assertTrue(callable(eljay.build_registry))
+
+    def test_resolve_model_callable(self):
+        import eljay
+        self.assertTrue(callable(eljay.resolve_model))
+
+
+class OutputDirectoryTests(unittest.TestCase):
+    def test_agent_outputs_dir_exists_or_can_create(self):
+        """Ensure the .agent/outputs directory structure can be created."""
+        from pathlib import Path
+        root = Path(__file__).resolve().parent.parent
+        outputs = root / ".agent" / "outputs"
+        images = outputs / "images"
+        videos = outputs / "videos"
+        images.mkdir(parents=True, exist_ok=True)
+        videos.mkdir(parents=True, exist_ok=True)
+        self.assertTrue(images.exists())
+        self.assertTrue(videos.exists())
+
+
+class ProviderFactoryTests(unittest.TestCase):
+    """Verify all four provider classes can be instantiated."""
+
+    def test_ollama_provider_instantiable(self):
+        from agent.providers.ollama import OllamaProvider
+        p = OllamaProvider()
+        self.assertEqual(p.name, "ollama")
+        self.assertIn("text", p.capabilities)
+
+    def test_web_search_provider_instantiable(self):
+        from agent.providers.web import WebSearchProvider
+        p = WebSearchProvider()
+        self.assertEqual(p.name, "duckduckgo")
+        self.assertIn("web-search", p.capabilities)
+
+    def test_image_provider_instantiable(self):
+        from agent.providers.image import ImageProvider
+        p = ImageProvider()
+        self.assertEqual(p.name, "image-local")
+
+    def test_video_provider_instantiable(self):
+        from agent.providers.video import VideoProvider
+        p = VideoProvider()
+        self.assertEqual(p.name, "video-local")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/tests/test_workspace.py

@@ -0,0 +1,221 @@
+"""Deterministic tests for the workspace module — no model, no network.
+
+Run from the project root:
+    python tests/test_workspace.py
+"""
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from agent.workspace import (  # noqa: E402
+    Workspace,
+    find_project_root,
+    human_size,
+)
+
+
+class WorkspaceTests(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+        (self.root / "a.py").write_text("print('hi')\n", encoding="utf-8")
+        (self.root / "sub").mkdir()
+        (self.root / "sub" / "b.txt").write_text("hello", encoding="utf-8")
+        (self.root / "node_modules").mkdir()
+        (self.root / "node_modules" / "x.js").write_text("ignore me", encoding="utf-8")
+        self.ws = Workspace(self.root)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    # -- safety ------------------------------------------------------------
+
+    def test_resolve_allows_paths_inside_root(self):
+        self.assertEqual(self.ws.resolve("sub"), (self.root / "sub").resolve())
+
+    def test_resolve_rejects_escape_attempts(self):
+        with self.assertRaises(ValueError):
+            self.ws.resolve("..")
+        with self.assertRaises(ValueError):
+            self.ws.resolve("../../etc/passwd")
+
+    def test_resolve_rejects_absolute_path_outside_root(self):
+        with self.assertRaises(ValueError):
+            self.ws.resolve(str(self.root.parent))
+
+    # -- listing -----------------------------------------------------------
+
+    def test_list_tree_shows_files_and_dirs(self):
+        out = self.ws.list_tree(depth=3)
+        self.assertIn("a.py", out)
+        self.assertIn("sub/", out)
+        self.assertIn("b.txt", out)
+
+    def test_list_tree_skips_ignored_dirs(self):
+        out = self.ws.list_tree(depth=3)
+        self.assertNotIn("node_modules", out)
+        self.assertNotIn("x.js", out)
+
+    def test_list_tree_respects_depth(self):
+        out = self.ws.list_tree(depth=1)
+        self.assertIn("sub/", out)
+        self.assertNotIn("b.txt", out)  # one level down should be hidden
+
+    def test_list_tree_truncates(self):
+        for i in range(20):
+            (self.root / f"file_{i}.txt").write_text("x", encoding="utf-8")
+        out = self.ws.list_tree(depth=2, max_entries=5)
+        self.assertIn("truncated", out)
+
+    def test_list_tree_missing_path_reports_error(self):
+        out = self.ws.list_tree(rel="does_not_exist")
+        self.assertIn("does not exist", out)
+
+    def test_list_tree_outside_root_reports_error(self):
+        out = self.ws.list_tree(rel="../..")
+        self.assertIn("ERROR", out)
+
+    # -- detection ---------------------------------------------------------
+
+    def test_find_project_root_from_nested_dir(self):
+        (self.root / ".git").mkdir()
+        nested = self.root / "deep" / "deeper"
+        nested.mkdir(parents=True)
+        self.assertEqual(find_project_root(nested), self.root.resolve())
+
+    def test_detect_stack_react(self):
+        (self.root / "package.json").write_text(
+            json.dumps({"dependencies": {"react": "^18.0.0"}}), encoding="utf-8"
+        )
+        stacks = self.ws.detect_stack()
+        self.assertIn("Node.js", stacks)
+        self.assertIn("React", stacks)
+
+    def test_detect_stack_laravel(self):
+        (self.root / "artisan").write_text("", encoding="utf-8")
+        (self.root / "composer.json").write_text(
+            json.dumps({"require": {"laravel/framework": "^11.0"}}), encoding="utf-8"
+        )
+        stacks = self.ws.detect_stack()
+        self.assertIn("PHP", stacks)
+        self.assertIn("Laravel", stacks)
+
+    def test_detect_stack_database_from_env(self):
+        (self.root / ".env").write_text("DB_CONNECTION=mysql\n", encoding="utf-8")
+        self.assertIn("MySQL", self.ws.detect_stack())
+
+    # -- reading -----------------------------------------------------------
+
+    def test_read_file_returns_numbered_lines(self):
+        out = self.ws.read_file("sub/b.txt")
+        self.assertIn("hello", out)
+        self.assertIn("1 |", out)
+
+    def test_read_file_line_range(self):
+        (self.root / "nums.txt").write_text(
+            "\n".join(f"line{i}" for i in range(1, 11)) + "\n", encoding="utf-8"
+        )
+        out = self.ws.read_file("nums.txt", start_line=3, end_line=5)
+        self.assertIn("line3", out)
+        self.assertIn("line5", out)
+        self.assertNotIn("line2", out)
+        self.assertNotIn("line6", out)
+
+    def test_read_file_refuses_directory(self):
+        out = self.ws.read_file("sub")
+        self.assertIn("is a directory", out)
+
+    def test_read_file_refuses_binary(self):
+        (self.root / "blob.bin").write_bytes(b"PNG\x00\x01\x02binary")
+        out = self.ws.read_file("blob.bin")
+        self.assertIn("binary", out.lower())
+
+    def test_read_file_refuses_large_file_without_range(self):
+        (self.root / "big.txt").write_text("a" * 1_100_000, encoding="utf-8")
+        out = self.ws.read_file("big.txt")
+        self.assertIn("larger than", out)
+
+    def test_read_file_large_file_with_range_is_allowed(self):
+        # >1 MB file made of many short lines, so a small range stays small.
+        (self.root / "big2.txt").write_text("x\n" * 600_000, encoding="utf-8")
+        out = self.ws.read_file("big2.txt", start_line=1, end_line=2)
+        self.assertNotIn("larger than", out)
+        self.assertIn("1 |", out)
+
+    def test_read_file_outside_root_is_rejected(self):
+        out = self.ws.read_file("../../secret.txt")
+        self.assertIn("ERROR", out)
+
+    def test_read_file_missing_reports_error(self):
+        out = self.ws.read_file("nope.txt")
+        self.assertIn("does not exist", out)
+
+    def test_read_file_reversed_range_reports_error(self):
+        out = self.ws.read_file("a.py", start_line=5, end_line=2)
+        self.assertIn("ERROR", out)
+
+    # -- searching ---------------------------------------------------------
+
+    def test_search_finds_literal_with_line_number(self):
+        (self.root / "code.py").write_text(
+            "x = 1\ndef useAuth():\n    pass\n", encoding="utf-8"
+        )
+        out = self.ws.search("useAuth")
+        self.assertIn("code.py:2:", out)
+        self.assertIn("def useAuth", out)
+
+    def test_search_is_case_insensitive_by_default(self):
+        (self.root / "code.py").write_text("UseAuth()\n", encoding="utf-8")
+        self.assertIn("code.py", self.ws.search("useauth"))
+
+    def test_search_case_sensitive(self):
+        (self.root / "code.py").write_text("UseAuth()\n", encoding="utf-8")
+        self.assertIn("No matches", self.ws.search("useauth", case_sensitive=True))
+
+    def test_search_regex(self):
+        (self.root / "code.py").write_text("foo123\nbar\n", encoding="utf-8")
+        self.assertIn("foo123", self.ws.search(r"foo\d+", regex=True))
+
+    def test_search_invalid_regex_reports_error(self):
+        self.assertIn("ERROR", self.ws.search("([", regex=True))
+
+    def test_search_empty_query_reports_error(self):
+        self.assertIn("ERROR", self.ws.search(""))
+
+    def test_search_missing_path_reports_error(self):
+        self.assertIn("ERROR", self.ws.search("x", rel="nope"))
+
+    def test_search_skips_ignored_dirs(self):
+        (self.root / "node_modules" / "x.js").write_text("needle\n", encoding="utf-8")
+        self.assertIn("No matches", self.ws.search("needle"))
+
+    def test_search_skips_binary_files(self):
+        (self.root / "blob.bin").write_bytes(b"\x00needle")
+        self.assertIn("No matches", self.ws.search("needle"))
+
+    def test_search_truncates_at_max_results(self):
+        (self.root / "many.txt").write_text("hit\n" * 20, encoding="utf-8")
+        out = self.ws.search("hit", max_results=5)
+        self.assertIn("truncated", out)
+
+    def test_search_scoped_to_subdir_excludes_elsewhere(self):
+        (self.root / "a.py").write_text("needle\n", encoding="utf-8")
+        (self.root / "sub" / "b.txt").write_text("needle\n", encoding="utf-8")
+        out = self.ws.search("needle", rel="sub")
+        self.assertIn("b.txt", out)
+        self.assertNotIn("a.py", out)
+
+    def test_human_size(self):
+        self.assertEqual(human_size(0), "0 B")
+        self.assertEqual(human_size(512), "512 B")
+        self.assertEqual(human_size(2048), "2.0 KB")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)